motionspec 1.0.3 → 1.0.5

package/README.md

@@ -1,6 +1,6 @@
 # MotionSpec
 
-A formal intermediate language for scroll-driven web motion. A small model translates a request into a **schema-validated JSON spec**; a **deterministic compiler** turns that spec into GSAP/CSS — hallucination-proof by construction, with an enforced `prefers-reduced-motion` fallback and a performance budget.
+A formal intermediate language for scroll-driven web motion. A small model translates a request into a **schema-validated JSON spec**; a **deterministic compiler** turns that spec into GSAP/CSS — injection-proof & catalog-validated by construction, with an enforced `prefers-reduced-motion` fallback and a performance budget.
 
 The thesis: **capability lives in the catalog, not the model.** A bigger model can write more elaborate specs, but it can never emit a primitive, parameter, or selector the Trust Boundary hasn't approved. The compiler trusts only what passes.
 
@@ -20,17 +20,17 @@ request ──> Routing (small model, Stage A) ──> MotionSpec (JSON)
 
 | | |
 |---|---|
-| Version | **v1.0.3** · schema frozen at spec v1 (ADR-0001, signed) |
+| Version | **v1.0.4** · schema frozen at spec v1 (ADR-0001, signed) |
 | Published | **npm `motionspec`** · MCP Registry `io.github.MasterPlayspots/motionspec` |
-| Tests | **155** green · CI on Node 18/20/22 |
+| Tests | **full suite green** · CI on Node 18/20/22 |
 | Catalog | **8** primitives, all device-verified |
 | Dependencies | **0 vulnerabilities** · SBOM committed · all permissive licenses |
-| Coverage | **98.4% lines / 95.9% functions** of `src/` + `worker/` (CI gate fails under 90%) |
-| Machine audit | 7.2/10 (Production-Ready), independently re-audited |
+| Coverage | **≈98% lines / ≈96% functions / ≈82% branches** of `src/` + `worker/` (CI gate: 90/90/75) |
+| Machine audit | internal re-audits ≈8.7 (engine) — see `docs/analysis/` |
 | First client | CHS Computer — live on Vercel |
-| Hosted MCP | **live** — private, secret-gated Cloudflare Worker · per-minute cron canary + external heartbeat (synthetic error → email in <5 min, proven) · gated `/dashboard` |
+| Hosted MCP | **live** — private, per-key gated (KV registry) Cloudflare Worker · per-minute cron canary + external heartbeat (synthetic error → email in <5 min, proven) · gated `/dashboard` |
 
-Schema v1 is frozen: `specVersion "1.0"` is the stable public contract; `"0.1"` is deprecated and accepted until v1.2. The `[MS-XXX]` error-code registry is public API. Phase B (test & security) is closed — CI is green on the x86 runner incl. Playwright `e2e` for every primitive (all jobs pass on every push to `main` — see the repo Actions tab; the x86 runner is the source of truth). **Phase C (observability + hosted MCP) is live and gate-proven**: the MCP server runs as a private, secret-gated Cloudflare Worker; a per-minute cron canary runs `validate→compile` and pings an external heartbeat, so a failure alerts by email within 5 minutes (verified on real infra). A gated `/dashboard` renders live telemetry.
+Schema v1 is frozen: `specVersion "1.0"` is the stable public contract; `"0.1"` is deprecated and accepted until v1.2. The `[MS-XXX]` error-code registry is public API. Phase B (test & security) is closed — CI is green on the x86 runner incl. Playwright `e2e` for every primitive (all jobs pass on every push to `main` — CI status available on request). **Phase C (observability + hosted MCP) is live and gate-proven**: the MCP server runs as a private, per-key gated (KV registry) Cloudflare Worker; a per-minute cron canary runs `validate→compile` and pings an external heartbeat, so a failure alerts by email within 5 minutes (verified on real infra). A gated `/dashboard` renders live telemetry.
 
 ## Install
 
@@ -47,11 +47,15 @@ claude mcp add motionspec -- npx motionspec
 
 Listed on the MCP Registry as `io.github.MasterPlayspots/motionspec`.
 
-## Quickstart (from a clone of the repo)
+> **Source:** The npm package and the hosted MCP are public. The source
+> repository is **private (access by arrangement)**. Sections below that
+> reference a repo clone assume granted source access.
+
+## Quickstart (with source access)
 
 ```bash
 npm ci                                      # install (0 runtime deps beyond MCP SDK + zod)
-npm test                                    # 151 tests: validator, compiler-golden, router, fuzz, schema parity, worker contract
+npm test                                    # full suite: validator, compiler-golden, router, fuzz, schema parity, worker contract
 node bin/motion.js catalog                  # primitives + catalog version (16-char hash)
 node bin/motion.js compile examples/hero.motionspec.json
 node bin/motion.js pipeline "Hero headline fades in, cards staggered" --mock
@@ -87,7 +91,7 @@ Tools: `motion_catalog` (primitives + authoring rules) · `motion_validate` (fai
 
 1. **Allow-list** — a primitive not in the catalog never reaches the compiler.
 2. **Injection-proof** — ids, selectors, string params and triggers are charset-validated; every interpolation is a JS literal (`JSON.stringify`) or a CSS-screened raw value. Malicious model output is rejected fail-closed (tested + fuzzed over 6000 random specs).
-3. **a11y** — `respectReducedMotion` gates JS and CSS; the model cannot switch it off.
+3. **a11y** — `respectReducedMotion` is **default-on at the compiler level** (fail-safe): omitting `globals` or the field yields a `prefers-reduced-motion` guard. Setting `globals.respectReducedMotion: false` is accepted but emits a compiler warning (`MS-GLOBALS-RRM-OFF`); a prompt-only instruction is not sufficient to disable the guard.
 4. **Determinism** — same spec ⇒ identical code (golden-file tests).
 5. **Versioned** — schema frozen v1; catalog SemVer enforced by a diff-gate; specs may pin `catalogVersion` for reproducibility (`MS-CATALOG-PIN-MISMATCH` fail-closed).
 6. **Observability** — every request logs `model | model-repaired | cache-hit | escalate-*` to `telemetry/events.jsonl`; escalation clusters are the signal for new primitives (concept §3.3).
@@ -102,7 +106,7 @@ src/compiler/    catalog.js · catalog-semver.js · validate.js (Trust Boundary)
 src/router/      prompt.js · clients.js (openai-compat + mock) · route.js · cache.js · telemetry.js
 src/mcp/         server.mjs (4 tools, fail-closed, input-capped)
 bin/             motion.js (CLI) · catalog-lock.js · license-check.js
-test/            151 tests incl. injection attacks, fuzz, golden files, schema parity, worker contract; test/e2e (Playwright)
+test/            test suite incl. injection attacks, fuzz, golden files, schema parity, worker contract; test/e2e (Playwright)
 docs/            ADR-0001 (schema freeze) · ROADMAP_TO_10 · PHASE_A_REAUDIT · CLAUDE_CODE_HANDOFF
 ```
 
@@ -113,7 +117,17 @@ Concept, research, pitch, business docs and the CHS client site live in the sibl
 - `docs/CLAUDE_CODE_HANDOFF.md` — **start here when continuing in Claude Code (terminal).**
 - `docs/ROADMAP_TO_10_2026-06-15.md` — the production path to a proven 10/10 (Phases A–G, anti-goals, machine gates).
 - `docs/adr/0001-schema-freeze-v1.md` — the frozen v1 contract and why.
-- `docs/PHASE_A_REAUDIT_2026-06-15.md` — independent re-audit findings + fixes.
+- `docs/PHASE_A_REAUDIT_2026-06-15.md` — internal re-audit findings + fixes.
+
+## Contributing
+
+The source repository is currently **private (access by arrangement)**; the
+contributor guide and issue templates referenced below become available once
+source access is granted.
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the
+gate-driven PR checklist, commit conventions, and a short architecture tour. Bug
+reports and feature requests have issue templates under `.github/ISSUE_TEMPLATE/`.
 
 ## License
 

package/bin/assert-canonical.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * assert-canonical.js — Canonical-Guard (ops/canonical-guard).
+ * ------------------------------------------------------------
+ * Faellt FAIL-CLOSED (exit 1), wenn aus einem nicht-kanonischen Klon
+ * publiziert/deployed werden soll. Adressiert den wiederkehrenden Fehler
+ * "aus dem falschen / iCloud-gesyncten Klon veroeffentlicht" (siehe CANONICAL.md).
+ *
+ * Zwei unabhaengige Pruefungen, OR-verknuepft (eine reicht zum Blockieren):
+ *   1) git remote.origin.url zeigt NICHT auf MasterPlayspots/motionspec.
+ *   2) Arbeitsverzeichnis (pwd -P / realpath) liegt in einem iCloud-/Sync-Pfad:
+ *      "Library/Mobile Documents", "/Desktop/" oder "/Documents/".
+ *
+ * Eingehaengt in `prepublishOnly` (vor allen anderen Checks) und in
+ * `predeploy:worker`. Reine Pruef-Logik ist als evaluateCanonical() exportiert,
+ * damit sie ohne echtes git/cwd unit-testbar ist (test/canonical-guard.test.js).
+ */
+const { execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+
+const CANONICAL_SLUG = "MasterPlayspots/motionspec";
+/* iCloud-/Sync-Marker im Pfad. "Library/Mobile Documents" = iCloud Drive;
+ * Desktop/Documents werden auf macOS standardmaessig nach iCloud gespiegelt. */
+const ICLOUD_MARKERS = ["Library/Mobile Documents", "/Desktop/", "/Documents/"];
+
+/**
+ * Reine Entscheidungsfunktion — keine Seiteneffekte.
+ * @param {{ cwd: string, remoteUrl: string }} input
+ * @returns {{ ok: boolean, reasons: string[] }}
+ */
+function evaluateCanonical({ cwd, remoteUrl }) {
+  const reasons = [];
+
+  // (1) Remote pruefen. Akzeptiert https / git+https / git@ host, mit/ohne .git.
+  const norm = String(remoteUrl || "").trim().replace(/\/+$/, "");
+  const slugRe = new RegExp("[:/]" + CANONICAL_SLUG + "(?:\\.git)?$", "i");
+  if (!slugRe.test(norm)) {
+    reasons.push(
+      "remote.origin.url ist nicht " + CANONICAL_SLUG +
+      " (gefunden: " + (norm || "<leer>") + ")"
+    );
+  }
+
+  // (2) cwd auf iCloud-/Sync-Marker pruefen. Trailing-Slash anfuegen, damit ein
+  //     Verzeichnis, das exakt auf "/Desktop" endet, ebenfalls greift.
+  const haystack = String(cwd || "") + "/";
+  const hit = ICLOUD_MARKERS.find((m) => haystack.includes(m));
+  if (hit) {
+    reasons.push('Arbeitsverzeichnis liegt in iCloud-/Sync-Pfad ("' + hit + '"): ' + cwd);
+  }
+
+  return { ok: reasons.length === 0, reasons };
+}
+
+/* --- CLI-Wrapper: liest echtes cwd + git-Remote, exit 1 bei FAIL ------------ */
+function readRemoteUrl() {
+  try {
+    return execFileSync("git", ["config", "--get", "remote.origin.url"], {
+      encoding: "utf8",
+    }).trim();
+  } catch {
+    return ""; // kein Remote => faellt unter (1) durch
+  }
+}
+
+function main() {
+  // pwd -P : Symlinks aufloesen, damit ein iCloud-Pfad nicht hinter einem
+  // Symlink versteckt werden kann.
+  let cwd;
+  try { cwd = fs.realpathSync(process.cwd()); } catch { cwd = process.cwd(); }
+  const remoteUrl = readRemoteUrl();
+
+  const { ok, reasons } = evaluateCanonical({ cwd, remoteUrl });
+  if (!ok) {
+    console.error("Canonical-Guard FAIL — nicht aus diesem Klon publishen/deployen:");
+    reasons.forEach((r) => console.error("  - " + r));
+    console.error("Kanonisch ist " + CANONICAL_SLUG + " unter ~/dev/* (siehe CANONICAL.md).");
+    process.exit(1);
+  }
+  console.error("Canonical-Guard OK — " + CANONICAL_SLUG + " @ " + cwd);
+}
+
+if (require.main === module) main();
+
+module.exports = { evaluateCanonical, CANONICAL_SLUG, ICLOUD_MARKERS };

package/bin/forge.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * Forge-CLI (Baustein 4) — Subcommands wie bin/motion.js.
+ * ----------------------------------------------------------------------
+ *   node bin/forge.js queue                       Priorisierte Bau-Queue (aus forge.gaps.json)
+ *   node bin/forge.js next                         Top-Luecke
+ *   node bin/forge.js generate "<gapKey>" [--mock] [--emit-name]
+ *                                                  Kandidat aus einer Luecke erzeugen
+ *   node bin/forge.js verify <name>                promote-gate verify-only
+ *
+ * Luecken-Quelle: forge.gaps.json (optional) — entweder ein Array von discover-Gaps
+ *   [{ what, target }]  ODER  { gaps:[...], telemetry:[{pattern,count}] }.
+ * Ohne --mock braucht generate ein Modell (MOTION_API_KEY / MOTION_MODEL).
+ *
+ * ANTI-GOALS: erzeugt NUR Kandidaten + PR-Material; promotet/published/deployt NIE.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const { prioritize } = require("../src/forge/prioritize.js");
+const { generate } = require("../src/forge/generate.js");
+const { gate } = require("./promote-gate.js");
+const { mockForgeClient, openAICompatClient } = require("../src/router/clients.js");
+
+function loadGaps() {
+  const f = path.join(ROOT, "forge.gaps.json");
+  if (!fs.existsSync(f)) return { gaps: [], telemetry: [] };
+  let data;
+  try { data = JSON.parse(fs.readFileSync(f, "utf8")); }
+  catch (e) { console.error("forge.gaps.json kein gueltiges JSON: " + e.message); return { gaps: [], telemetry: [] }; }
+  if (Array.isArray(data)) return { gaps: data, telemetry: [] };
+  return { gaps: data.gaps || [], telemetry: data.telemetry || [] };
+}
+
+function queue() {
+  const { gaps, telemetry } = loadGaps();
+  return prioritize(gaps, telemetry);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  const flags = new Set(argv.filter((a) => a.startsWith("--")));
+  const arg = argv.slice(1).find((a) => !a.startsWith("--"));
+  const emitName = flags.has("--emit-name");
+
+  if (cmd === "queue") {
+    const q = queue();
+    if (!q.length) { console.log("Queue leer (forge.gaps.json fehlt oder keine Luecken)."); return; }
+    console.log("\n  Forge-Queue (" + q.length + " Muster, score-absteigend):\n");
+    q.forEach((e, i) => console.log("   " + (i + 1) + ". " + e.pattern + "  [score " + e.score + ", exemplars: " + (e.exemplars.join(", ") || "—") + "]"));
+    console.log("");
+    return;
+  }
+
+  if (cmd === "next") {
+    const q = queue();
+    if (!q.length) { if (!emitName) console.log("Queue leer."); process.exitCode = 1; return; }
+    if (emitName) console.log(q[0].gapKey);
+    else console.log("\n  Naechste Luecke: " + q[0].pattern + "  [score " + q[0].score + "]\n");
+    return;
+  }
+
+  if (cmd === "verify") {
+    if (!arg) { console.error("Aufruf: node bin/forge.js verify <name>"); process.exit(2); }
+    const r = gate(arg, { write: !flags.has("--no-report") });
+    if (!emitName) {
+      console.log("\n  Verify — " + arg + "\n");
+      for (const c of r.checks) console.log("   " + (c.info ? (c.ok ? "i" : "!") : (c.ok ? "OK" : "x ")) + "  " + c.label + (c.detail ? "  — " + c.detail : ""));
+      console.log("\n  " + (r.pass ? "PASS" : "FAIL") + "\n");
+    }
+    if (!r.pass) process.exitCode = 1;
+    return;
+  }
+
+  if (cmd === "generate") {
+    // Luecke bestimmen: expliziter gapKey ODER Top der Queue.
+    let gap = arg;
+    if (!gap) {
+      const q = queue();
+      if (!q.length) { if (!emitName) console.error("Keine Luecke angegeben und Queue leer."); process.exitCode = 1; return; }
+      gap = q[0]; // prioritize-Eintrag (hat what/pattern/exemplars)
+    }
+    const client = flags.has("--mock") ? mockForgeClient() : openAICompatClient();
+    let res;
+    try { res = await generate(gap, { client }); }
+    catch (e) { if (!emitName) console.error("generate fehlgeschlagen: " + e.message); process.exitCode = 1; return; }
+
+    if (res.ok) {
+      if (emitName) console.log(res.name);
+      else console.log("\n  Kandidat erzeugt: " + path.relative(process.cwd(), res.candidatePath) + "  (Gauntlet GRUEN — Taste-Review offen)\n");
+      return;
+    }
+    // Eskalation: kein PR-faehiger Kandidat.
+    if (!emitName) console.error("\n  ESKALIERT" + (res.name ? " (" + res.name + ")" : "") + ": " + (res.reason || "—") + "\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  console.error("Befehle: queue | next | generate <gapKey> [--mock] [--emit-name] | verify <name>");
+  process.exit(2);
+}
+
+main().catch((e) => { console.error("Fehler: " + e.message); process.exit(1); });

package/bin/motion.js

@@ -79,7 +79,7 @@ async function main() {
   }
 
   if (cmd === "stats") {
-    const s = telemetry.summary();
+    const s = await telemetry.summary();
     console.log("Telemetrie: " + s.total + " Ereignisse");
     Object.keys(s.byOutcome).forEach((k) => console.log("  " + k + ": " + s.byOutcome[k]));
     return;

package/bin/promote-gate.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * Promote-Gate (Baustein 2) — die Gauntlet um die bestehenden Gates.
+ * ----------------------------------------------------------------------
+ *   node bin/promote-gate.js <name> [--prepare] [--no-report] [--budget=N]
+ *
+ * Liest candidates/<name>/<name>.json + candidates/<name>/example.motionspec.json,
+ * faehrt alle Gates (jede Stufe fail-closed) und liefert einen PASS/FAIL-Report
+ * (stdout + candidates/<name>/GATE_REPORT.md).
+ *
+ *   verify-only (default) : prueft, aendert NICHTS an primitives/.
+ *   --prepare             : bei PASS schreibt es die Promotion in den Arbeitsbaum
+ *                           (kopiert nach primitives/, ergaenzt optional die
+ *                           Keyword-Regel) — committet/merged NICHTS (Tor 1 = Mensch).
+ *
+ * ANTI-GOALS (verbindlich):
+ *   A2  promotet nie auf main / merged nie — schreibt hoechstens den Arbeitsbaum.
+ *   A4  KEIN Versions-Bump, KEIN Relock im Auto-Pfad. Die additive-minor-Eigenschaft
+ *       wird von catalog-lock ERZWUNGEN (Stufe 7 verifiziert sie), nicht hier gesetzt.
+ *   A6  Determinismus ist heilig — Stufe 6 verwirft nicht-deterministischen Output.
+ *
+ * Die testbare Logik lebt in diesem Modul (`gate`); der CLI-Wrapper ruft sie nur.
+ *
+ * Stufen (in dieser Reihenfolge, alle fail-closed ausser den als INFO markierten):
+ *   1  Primitiv gegen Meta-Schema (catalog.checkPrimitive) + reducedMotionFallback vorhanden
+ *   2  validateSpec(example) gegen den Katalog INKL. Kandidat
+ *   3  compileSpec(example) -> ok
+ *   4  report.budgetOk === true
+ *   5  reduced-motion-Guard im Artefakt (wenn respectReducedMotion an)
+ *   6  Determinismus: zweimal kompilieren -> byte-identisch; keine nicht-det. Tokens;
+ *      Golden stabil (candidates/<name>/<name>.golden.{js,css}) — fehlt -> nur mit --prepare anlegen
+ *   7  catalog-lock-Klassifikation: hypothetisch hinzugefuegt -> `added`/minor, KEINE Violations
+ *   8  INFO: WAAPI-Lowering-Bereitschaft (neues Primitiv ohne Lowering -> Gate-1-Mensch)
+ */
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const { loadCatalog, checkPrimitive, screenPattern } = require("../src/compiler/catalog.js");
+const { validateSpec } = require("../src/compiler/validate.js");
+const { compileSpec } = require("../src/compiler/compile.js");
+const { snapshotCatalog, diffCatalog } = require("../src/compiler/catalog-semver.js");
+const { SUPPORTED, lowerWaapi } = require("../src/compiler/lower-waapi.js");
+
+/* Gueltiger Katalog-/Kandidatenname (identisch zu generate.slugName + catalog NAME_RE).
+ * Wird VOR jedem Dateizugriff geprueft -> kein Path-Traversal ueber `name`. */
+const NAME_RE = /^[A-Za-z][A-Za-z0-9]{1,40}$/;
+
+/* Versions-Banner normalisieren — Golden duerfen nicht bei jedem Versions-Bump brechen. */
+const normVer = (s) => String(s == null ? "" : s).replace(/MotionSpec-Compiler v[0-9]+\.[0-9]+\.[0-9]+/g, "MotionSpec-Compiler vX");
+
+/* Tokens, die nicht-deterministischen Laufzeit-Output verraten (Anti-Goal A6).
+ * WICHTIG: eine Denylist kann NIE vollstaendig sein — sie ist ein starkes Netz,
+ * NICHT der alleinige Beweis. Determinismus ist auch Gate-1-Menschen-Pflicht.
+ * Deckt gaengige Formen ab inkl. Klammerzugriff (Math[...]) und blanker Date(). */
+const NONDETERMINISTIC_RE = new RegExp([
+  "Math\\s*\\.\\s*random", "Math\\s*\\[",
+  "Date\\s*\\.\\s*(now|parse|UTC)", "new\\s+Date", "\\bDate\\s*\\(",
+  "performance\\s*\\.\\s*(now|timeOrigin)",
+  "crypto\\s*\\.\\s*(randomUUID|getRandomValues)", "getRandomValues",
+  "hrtime", "process\\s*\\.\\s*hrtime",
+].join("|"), "i");
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function reducedMotionFallbackOf(prim) {
+  if (!prim || typeof prim !== "object") return null;
+  if (prim.a11y && prim.a11y.reducedMotionFallback) return prim.a11y.reducedMotionFallback;
+  if (prim.reducedMotionFallback) return prim.reducedMotionFallback; // Skelett-Form (top-level) ebenfalls akzeptieren
+  return null;
+}
+
+/**
+ * @typedef {Object} GateCheck
+ * @property {string} label
+ * @property {boolean} ok
+ * @property {string} [detail]
+ * @property {boolean} [info]  - true: Befund, der den PASS NICHT blockiert (Gate-1-Mensch)
+ */
+
+/**
+ * Faehrt die Gauntlet fuer einen Kandidaten. Aendert nichts ausser optional
+ * GATE_REPORT.md und (nur mit prepare) dem Arbeitsbaum.
+ * @param {string} name
+ * @param {{root?:string,candidatesDir?:string,primitivesDir?:string,lockPath?:string,prepare?:boolean,write?:boolean,budget?:number}} [opts]
+ * @returns {{pass:boolean, checks:GateCheck[], reportPath:string|null}}
+ */
+function gate(name, opts = {}) {
+  const root = opts.root || ROOT;
+  const candidatesDir = opts.candidatesDir || path.join(root, "candidates");
+  const primitivesDir = opts.primitivesDir || path.join(root, "primitives");
+  const lockPath = opts.lockPath || path.join(root, "catalog.lock.json");
+  const write = opts.write !== false;
+  const prepare = !!opts.prepare;
+  const budget = typeof opts.budget === "number" ? opts.budget : 10;
+
+  const checks = [];
+  const must = (label, ok, detail) => { checks.push({ label, ok: !!ok, detail: detail || "" }); return !!ok; };
+  const info = (label, ok, detail) => { checks.push({ label, ok: !!ok, detail: detail || "", info: true }); };
+
+  /* --- Stufe 0: Name-Format (fail-closed VOR jedem fs-Zugriff -> kein Path-Traversal) --- */
+  if (typeof name !== "string" || !NAME_RE.test(name)) {
+    checks.push({ label: "0 Name-Format gueltig", ok: false, detail: 'name "' + String(name).slice(0, 80) + '" verletzt ' + NAME_RE });
+    return { pass: false, checks, reportPath: null }; // NICHT finalize() -> kein mkdir/Write ausserhalb candidates/
+  }
+  const dir = path.join(candidatesDir, name);
+
+  /* --- Eingaben laden (fail-closed) --- */
+  const primFile = path.join(dir, name + ".json");
+  const exFile = path.join(dir, "example.motionspec.json");
+  let prim, example;
+  try { prim = readJson(primFile); }
+  catch (e) {
+    must("Kandidat-Primitiv lesbar", false, primFile + ": " + e.message);
+    return finalize(dir, checks, false, write, false, null, null, primitivesDir);
+  }
+  try { example = readJson(exFile); }
+  catch (e) {
+    must("Beispiel-Spec lesbar", false, exFile + ": " + e.message);
+    return finalize(dir, checks, false, write, false, null, null, primitivesDir);
+  }
+
+  /* Katalog INKL. Kandidat (in-memory Overlay; primitives/ wird NICHT angefasst). */
+  let base;
+  try { base = loadCatalog(primitivesDir); }
+  catch (e) {
+    must("Basis-Katalog laedt", false, e.message);
+    return finalize(dir, checks, false, write, false, prim, example, primitivesDir);
+  }
+  const overlaid = Object.assign({}, base, { [prim.name]: prim });
+  const isNewName = !Object.prototype.hasOwnProperty.call(base, prim.name);
+
+  /* --- Stufe 1: Meta-Schema + reducedMotionFallback --- */
+  let metaOk = true;
+  try { checkPrimitive(prim, name); }
+  catch (e) { metaOk = false; must("1 Meta-Schema (checkPrimitive)", false, e.message); }
+  if (metaOk) must("1 Meta-Schema (checkPrimitive)", true, "name/version/output/template/paramSchema gueltig");
+  must("1 reducedMotionFallback vorhanden", !!reducedMotionFallbackOf(prim),
+    reducedMotionFallbackOf(prim) || "fehlt — a11y.reducedMotionFallback ist Pflicht");
+  must("1 Name == prim.name", prim.name === name, prim.name === name ? "" : 'Dateibasis "' + name + '" != prim.name "' + prim.name + '"');
+  /* Determinismus-Screen schon auf dem ROHEN Template (faengt Entropie, die durch
+   * Interpolation verschleiert werden koennte — Compile bildet das Template 1:1 ab). */
+  const tplND = NONDETERMINISTIC_RE.exec(String(prim.template || ""));
+  must("1 keine nicht-det. Tokens im Template", !tplND, tplND ? ('template enthaelt "' + tplND[0] + '" (Anti-Goal A6)') : "");
+
+  /* --- Stufe 2: validateSpec --- */
+  const v = validateSpec(example, overlaid);
+  must("2 validateSpec(example)", v.ok, (v.errors || []).join(" | "));
+
+  /* --- Stufe 3 + 4: compile + Budget --- */
+  const c = v.ok ? compileSpec(example, overlaid, { specName: name, budget }) : { ok: false, errors: ["uebersprungen: validate fehlgeschlagen"] };
+  must("3 compileSpec(example) ok", c.ok, c.ok ? "" : (c.errors || []).join(" | "));
+  must("4 report.budgetOk", c.ok && c.report && c.report.budgetOk === true,
+    c.ok && c.report ? ("cost " + c.report.cost + " / " + c.report.budget) : "kein Report");
+
+  /* --- Stufe 5: reduced-motion-Guard im Artefakt — RRM ERZWUNGEN, vom Beispiel UNABHAENGIG ---
+   * Das Beispiel darf nicht steuern, ob sein eigenes a11y-Gate feuert: wir kompilieren
+   * eine RRM-on-Variante und verlangen den Guard. Das Beispiel-Opt-out bleibt nur INFO. */
+  const artifact = c.ok ? ((c.js || "") + "\n" + (c.css || "")) : "";
+  const forcedExample = Object.assign({}, example, { globals: Object.assign({}, example.globals, { respectReducedMotion: true }) });
+  const cForced = compileSpec(forcedExample, overlaid, { specName: name, budget });
+  const forcedArtifact = cForced.ok ? ((cForced.js || "") + "\n" + (cForced.css || "")) : "";
+  must("5 reduced-motion-Guard im Artefakt (RRM erzwungen)",
+    cForced.ok && forcedArtifact.includes("prefers-reduced-motion"),
+    cForced.ok ? "" : "kein Compile-Output bei erzwungenem respectReducedMotion");
+  if (example.globals && example.globals.respectReducedMotion === false)
+    info("5 example schaltet RRM aus", true, "Beispiel-Opt-out — Gate verifiziert den Guard unabhaengig (RRM erzwungen); Absicht prueft Gate-1");
+
+  /* --- Stufe 6: Determinismus + Golden --- */
+  if (c.ok) {
+    const c2 = compileSpec(example, overlaid, { specName: name, budget });
+    const deterministic = c2.ok && c2.js === c.js && c2.css === c.css;
+    /* HINWEIS: der Compiler ist eine reine Funktion -> diese Pruefung ist eine
+     * REGRESSIONSWACHE (faengt einen kuenftig unreinen Compiler), KEIN Laufzeit-
+     * Determinismus-Beweis. Letzteren leisten der Token-Screen (Stufe 1+6) + Golden. */
+    must("6 Compiler-Determinismus (Regressionswache)", deterministic, deterministic ? "" : "Output variiert zwischen zwei Laeufen — Compiler nicht mehr rein");
+    const nd = NONDETERMINISTIC_RE.exec(artifact);
+    must("6 keine nicht-det. Tokens im Output", !nd, nd ? ('Output enthaelt "' + nd[0] + '" (Anti-Goal A6)') : "");
+
+    const goldenJs = path.join(dir, name + ".golden.js");
+    const goldenCss = path.join(dir, name + ".golden.css");
+    const haveJs = fs.existsSync(goldenJs);
+    const haveCss = fs.existsSync(goldenCss);
+    if (!haveJs && !haveCss) {
+      if (prepare) {
+        if (c.js != null) fs.writeFileSync(goldenJs, normVer(c.js));
+        if (c.css != null) fs.writeFileSync(goldenCss, normVer(c.css));
+        info("6 Golden angelegt", true, "candidates/" + name + "/" + name + ".golden.* (--prepare)");
+      } else {
+        info("6 Golden fehlt", true, "wird bei --prepare angelegt; jetzt nur Determinismus geprueft");
+      }
+    } else {
+      let stable = true; const why = [];
+      if (haveJs) { const g = fs.readFileSync(goldenJs, "utf8"); if (normVer(c.js) !== g) { stable = false; why.push("js weicht ab"); } }
+      if (haveCss) { const g = fs.readFileSync(goldenCss, "utf8"); if (normVer(c.css) !== g) { stable = false; why.push("css weicht ab"); } }
+      must("6 Golden byte-stabil", stable, why.join("; "));
+    }
+  } else {
+    must("6 Determinismus", false, "kein Compile-Output zum Pruefen");
+  }
+
+  /* --- Stufe 7: catalog-lock-Klassifikation (additive minor) --- */
+  try {
+    const lock = readJson(lockPath).primitives;
+    const current = snapshotCatalog(overlaid);
+    const { violations, added } = diffCatalog(lock, current);
+    const noViolations = violations.length === 0;
+    const classedMinor = isNewName ? added.includes(prim.name) : true; // bereits gelockt -> kein neuer add, aber keine Violation = ok
+    must("7 catalog-lock: keine SemVer-Violations", noViolations, violations.map((x) => x.msg).join(" | "));
+    must("7 catalog-lock: additive minor", classedMinor,
+      isNewName ? ("erwartet in added[], war: " + JSON.stringify(added)) : "bereits im Lock (Re-Promotion) — keine Violation erforderlich");
+  } catch (e) {
+    must("7 catalog-lock-Klassifikation", false, e.message);
+  }
+
+  /* --- Stufe 8: INFO — WAAPI-Lowering-Bereitschaft --- */
+  if (Array.isArray(SUPPORTED) && SUPPORTED.includes(prim.name)) {
+    let lowered = false; let detail;
+    try {
+      const r1 = lowerWaapi(example, overlaid, { specName: name });
+      const r2 = lowerWaapi(example, overlaid, { specName: name });
+      lowered = r1.ok && r2.ok && (r1.js || r1.css) === (r2.js || r2.css);
+      detail = r1.ok ? "lowering deterministisch" : (r1.errors || []).join(" | ");
+    } catch (e) { detail = e.message; }
+    info("8 WAAPI-Lowering vorhanden", lowered, detail);
+  } else {
+    info("8 WAAPI-Lowering", true,
+      "neues Primitiv ohne Lowering — waapi-lowering.test.js wird in CI rot (SUPPORTED != Katalog). " +
+      "Das ist die Gate-1-Eskalation: ein Mensch ergaenzt Lowering+Golden, nicht die Forge (Anti-Goal A5).");
+  }
+
+  const pass = checks.filter((x) => !x.info).every((x) => x.ok);
+  return finalize(dir, checks, pass, write, prepare, prim, example, primitivesDir, isNewName);
+}
+
+/* Schreibt den Report und fuehrt (nur bei PASS+prepare) die Promotion durch. */
+function finalize(dir, checks, pass, write, prepare, prim, example, primitivesDir) {
+  const name = path.basename(dir);
+  let reportPath = null;
+  if (write) {
+    try {
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      reportPath = path.join(dir, "GATE_REPORT.md");
+      fs.writeFileSync(reportPath, renderReport(name, checks, pass, prepare && pass));
+    } catch { /* Report-Schreiben darf das Verdikt nicht kippen */ }
+  }
+  if (pass && prepare && prim) {
+    preparePromotion(name, prim, dir, primitivesDir);
+  }
+  return { pass, checks, reportPath };
+}
+
+/* preparePromotion: schreibt NUR in den Arbeitsbaum. KEIN git, KEIN Relock, KEIN
+ * Versions-Bump (Anti-Goal A4 — catalog-lock erzwingt die minor-Eigenschaft). */
+function preparePromotion(name, prim, dir, primitivesDir) {
+  const dest = path.join(primitivesDir, prim.name + ".json");
+  fs.writeFileSync(dest, JSON.stringify(prim, null, 2) + "\n");
+
+  // Optionale Keyword-Regel: candidates/<name>/keyword-rule.json oder prim.keywordRule.
+  let rule = null;
+  const ruleFile = path.join(dir, "keyword-rule.json");
+  if (fs.existsSync(ruleFile)) { try { rule = readJson(ruleFile); } catch { rule = null; } }
+  if (!rule && prim.keywordRule) rule = prim.keywordRule;
+  if (rule && rule.source && rule.target) {
+    try { appendKeywordRule(prim.name, rule, path.join(primitivesDir, "..", "src", "compiler", "keyword-map.js")); }
+    catch { /* best-effort: Keyword-Regel ist Gate-1-Komfort, kein hartes Gate */ }
+  }
+}
+
+/* Haengt eine Keyword->Primitiv-Regel an KEYWORD_MAP an (vor dem schliessenden `];`).
+ * Reihenfolge ist API, daher NEU = niedrigere Praezedenz als die spezifischen
+ * Bestandsregeln, was korrekt ist. Nutzt die new RegExp(...)-Form, um
+ * Literal-Escaping zu vermeiden. */
+function appendKeywordRule(primitiveName, rule, keywordMapFile) {
+  const flags = typeof rule.flags === "string" ? rule.flags : "i";
+  // Gleiche ReDoS-/Laengen-Schranke wie der Katalog (catalog.screenPattern):
+  // ein modell-kontrolliertes Muster darf NIE ungescreent in Laufzeit-Quellcode
+  // landen (die Tabelle wird auf untrusted Client-Briefs ausgefuehrt). Wirft bei
+  // Verstoss -> der best-effort try/catch in preparePromotion faengt es -> Regel
+  // wird einfach NICHT angehaengt (fail-closed).
+  screenPattern(rule.source, "keywordRule.source", (msg) => { throw new Error(msg); });
+  // Flags-Gueltigkeit zusaetzlich pruefen (screenPattern testet nur das Muster):
+  RegExp(rule.source, flags);
+  const src = fs.readFileSync(keywordMapFile, "utf8");
+  const entry =
+    "  /* forge: " + primitiveName + " (Taste-Review — Mensch prueft Reihenfolge/Praezedenz) */\n" +
+    "  { re: new RegExp(" + JSON.stringify(rule.source) + ", " + JSON.stringify(flags) + "), primitive: " +
+    JSON.stringify(primitiveName) + ", target: " + JSON.stringify(rule.target) +
+    ", params: " + JSON.stringify(rule.params || {}) + " },\n";
+  const marker = "];";
+  const idx = src.lastIndexOf(marker);
+  if (idx === -1) throw new Error("KEYWORD_MAP-Ende nicht gefunden");
+  const out = src.slice(0, idx) + entry + src.slice(idx);
+  fs.writeFileSync(keywordMapFile, out);
+}
+
+function renderReport(name, checks, pass, promoted) {
+  const lines = [];
+  lines.push("# Gate-Report — `" + name + "`");
+  lines.push("");
+  lines.push("**Verdikt: " + (pass ? "PASS" : "FAIL") + "**" + (promoted ? " · Promotion in den Arbeitsbaum vorbereitet (`--prepare`)" : ""));
+  lines.push("");
+  lines.push("> MASCHINELL GEPRUEFT. PASS heisst „alle Gates gruen“, NICHT „freigegeben“. Tor 1 = ein Mensch merged den PR (Taste-Review).");
+  lines.push("");
+  lines.push("| Stufe | OK | Detail |");
+  lines.push("| --- | :-: | --- |");
+  for (const c of checks) {
+    const mark = c.info ? (c.ok ? "i" : "!") : (c.ok ? "PASS" : "FAIL");
+    const detail = String(c.detail || "").replace(/\|/g, "\\|").slice(0, 300);
+    lines.push("| " + c.label + " | " + mark + " | " + detail + " |");
+  }
+  lines.push("");
+  lines.push("Legende: PASS/FAIL = fail-closed-Gate · i/! = INFO (blockiert PASS nicht; Hinweis fuer Gate-1).");
+  lines.push("");
+  return lines.join("\n");
+}
+
+module.exports = { gate, preparePromotion, appendKeywordRule, renderReport, reducedMotionFallbackOf };
+
+if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const flags = new Set(argv.filter((a) => a.startsWith("--")));
+  const name = argv.find((a) => !a.startsWith("--"));
+  if (!name) { console.error("Aufruf: node bin/promote-gate.js <name> [--prepare] [--no-report]"); process.exit(2); }
+  const budgetArg = argv.find((a) => a.startsWith("--budget="));
+  const r = gate(name, {
+    prepare: flags.has("--prepare"),
+    write: !flags.has("--no-report"),
+    budget: budgetArg ? Number(budgetArg.split("=")[1]) : undefined,
+  });
+  console.log("\n  Promote-Gate — " + name + "\n");
+  for (const c of r.checks) {
+    const mark = c.info ? (c.ok ? "i" : "!") : (c.ok ? "OK" : "x ");
+    console.log("   " + mark + "  " + c.label + (c.detail ? "  — " + c.detail : ""));
+  }
+  console.log("\n  " + (r.pass ? "PASS" : "FAIL") + (r.reportPath ? "  (" + path.relative(process.cwd(), r.reportPath) + ")" : "") + "\n");
+  if (!r.pass) process.exitCode = 1;
+}