Lokale Rust-CLI für synthetische Evidence-Pakete, deterministisches Replay, Kontext-Rendering und überprüfbare KI-Workflow-Artefakte.

Prototyp im Kontext des BMDS/SPARK-Hackathons: Evidence-, Replay- und Validierungsschicht für SPARK-artige Verwaltungs-KI-Workflows.

Modelle sind Provider. Kontext ist das Produkt.

flowchart LR
    roh["Synthetischer JSON-Trace"] --> schema["schema check"]
    schema --> compress["package compress"]
    compress --> spkg[".spkg Evidence-Paket"]

    spkg --> inspect["package inspect"]
    spkg --> verify["package verify"]
    spkg --> replay["package replay"]
    spkg --> adversarial["package adversarial"]

    schema --> report["report export"]
    report --> md["Markdown-Review-Report"]

    spkg --> build["context build"]
    build --> render["context render"]
    build --> notebook["notebook bundle"]
    render --> notebook
    notebook --> ipynb[".ipynb Review-Notebook"]

    classDef guard fill:#111827,stroke:#60a5fa,color:#e5e7eb;
    classDef artifact fill:#1f2937,stroke:#34d399,color:#e5e7eb;
    class schema,verify,adversarial guard;
    class spkg,md,ipynb artifact;

Sparkctl lässt sich als kleiner Evidence-Graph lesen:

flowchart TB
    sparkctl["Sparkctl"] --> cli["agy-ct CLI"]
    cli --> package["Package-Lifecycle"]
    cli --> context["Context-Lifecycle"]
    cli --> review["Review-Artefakte"]

    package --> spkg2[".spkg Evidence-Paket"]
    spkg2 --> integrity["Hash- und Ledger-Prüfungen"]
    spkg2 --> replay2["Deterministisches Replay"]
    spkg2 --> adversarial2["Adversarial-Simulation"]

    context --> build2["Strukturierter Kontext"]
    build2 --> render2["Token-sparendes Rendering"]
    build2 --> notebook2["Notebook-Bundle"]

    review --> report2["Markdown-Report"]
    review --> notebook2

    governance["Governance-Grenzen"] --> synthetic["Synthetic-only"]
    governance --> human["Human Review"]
    governance --> nonclaims["Keine Produktiv-/Rechts-/Compliance-Claims"]

    synthetic --> sparkctl
    human --> sparkctl
    nonclaims --> sparkctl

Dieser Graph ist bewusst README-nativ gehalten. Eine interaktive Ace-Knowledge-Graph-Variante kann später aus derselben Struktur generiert werden; die README bleibt jedoch ohne externe Runtime vollständig lesbar.

Der SPARK-Hackathon („Schnellere Planung und Realisierung durch KI“) sucht nach Wegen, Verwaltungsverfahren mithilfe von KI-Systemen sicherer und effizienter zu gestalten.

Sparkctl greift hierbei an einer kritischen Stelle an:

• Keine autonome Entscheidung: Das Tool trifft keine eigenen inhaltlichen oder rechtlichen Entscheidungen.
• Kontext-Sicherung: Es sorgt dafür, dass die an KI-Modelle übergebenen Kontextdaten (Traces) strukturiert, reproduzierbar und für den menschlichen Bearbeiter vollständig nachvollziehbar bleiben.
• Prüfbarkeit: Durch die Trennung von komprimierbarem Fließtext und aufzeichnungsrelevanten Metadaten bleibt die Historie der Bearbeitungsschritte auditierbar.

Dies ermöglicht sichere, transparente und nachvollziehbare Prototyp-Workflows für die KI-gestützte Sachbearbeitung.

Sparkctl implementiert Mechanismen zur Absicherung synthetischer Planungsdaten.

• agy-ct package compress — Komprimiert Roh-Traces zu einer .spkg-Datei unter Erhalt kritischer Hashes.
• agy-ct package inspect — Liest Sidecar-Eigenschaften und Header-Einträge aus .spkg.
• agy-ct package verify — Führt kryptografische SHA-256 Validierungen von .spkg-Evidence-Paketen durch.
• agy-ct package replay — Rekonstruiert die aufgezeichnete Trace deterministisch (strikte stdout/stderr Kanaltrennung).
• agy-ct package adversarial — Simuliert manipulierte Attribute zur Überprüfung der Manipulationserkennung.
• agy-ct report export — Exportiert JSON-Pipeline-Berichte als formatierten Markdown-Report.
• agy-ct notebook bundle — Bündelt Kontext-Zustände und Textrenderings in ein .ipynb Jupyter Notebook.
• agy-ct schema check — Gleicht rohe Trace-Dateien gegen JSON-Schemas ab.
• agy-ct context validate — Führt strukturelle Validierung und Leckprüfungen auf Kontextmodellen durch.
• agy-ct context build — Erzeugt strukturierte operative Kontextmodelle.
• agy-ct context render — Rendert operative Kontextdaten in token-sparenden Fließtext.

Führen Sie die folgenden sicheren lokalen Befehle im Rust-Unterverzeichnis aus:

# In das Rust-Verzeichnis wechseln
cd agy7rust

# Testsuite ausführen
cargo test

# Berichtsexport mit einer synthetischen Beispieldokumentation ausführen
cargo run --bin agy-ct -- report export -i ../examples/spark/report_sample.json -o ../temp_output.md

Hinweis: Befehle, die Berichte oder veränderte Artefakte generieren, sind optional und dienen dem manuellen Review-Prozess.

Sparkctl nutzt eine Reihe technischer Mechanismen, um die Integrität synthetischer Planungsdaten nachzuweisen:

• Canonical JSON: Um Abweichungen durch Formatierung, Leerzeichen oder Keys-Sortierung zu verhindern, werden JSON-Strukturen deterministisch sortiert und serialisiert.
• SHA-256 Hashing: Die Verifikation stützt sich auf SHA-256 Hashes der serialisierten Daten.
• Integrity Chain: Der Hash des Preimages (payload_sha256) wird mit dem Zustand des Sidecars verknüpft, um ein manipulationssensitives Evidence Package zu erzeugen.
• Adversarial-Simulation: Der package adversarial-Befehl simuliert gezielte Manipulationen an Paketstrukturen, um zu demonstrieren, wie Abweichungen vom kanonischen Hash sofort erkannt werden.
• Keine Sicherheits- oder Rechtsgarantie: Diese Absicherung dient ausschließlich der Erkennung unbeabsichtigter Datenverluste oder struktureller Abweichungen (tamper-sensitive validation). Sie stellt keine kryptografische Signatur im Sinne des Signaturgesetzes und kein forensisch unumstößliches Beweismittel dar.

Um Missverständnisse im Rahmen des SPARK-Hackathons auszuschließen, gelten folgende Grenzen:

flowchart TB
    prototype["Prototyp / Konzept-Demo"]
    synthetic2["Rein synthetische Daten"]
    human2["Menschliche Prüfung erforderlich"]
    local["Lokal-first / Offline"]
    noClaims["Keine Produktiv-, Rechts-, Forensik- oder Compliance-Claims"]

    prototype --> noClaims
    synthetic2 --> noClaims
    human2 --> noClaims
    local --> noClaims

Dieses Repository nutzt klare Richtlinien für die lokale Ausführung von KI-Entwicklungsagenten (z. B. Antigravity):

• Regelwerk: Die AGENTS.md ist das maßgebliche lokale Steuerungswerkzeug.
• Skill-Pfad: Das Verzeichnis .agents/skills/ dient als aktiver Antigravity-Skill-Pfad.
• Codex-Hooks: Skripte unter .codex/hooks/ sind Codex-spezifisch und bieten keine Ausführungs- oder Sicherheitsgarantie für Antigravity-Sitzungen.
• Sicherheits-Modus: Empfohlen wird die Ausführung im Sandbox-Modus (proceed-in-sandbox).

• Keine bekannten CLI-Platzhalter mehr.

• Erweiterung der synthetischen Planungs-Fixtures.
• Evaluierung von Community-Feedback zu Evidence-Strukturen.
• Optionale native Plugin- und Hook-Integrationen für verbesserte Absicherung.
• Optionaler Repo-Hygiene-Fix für alte Submodule-/Workflow-Warnungen.

• Feedback & Issues: Fragen, Anregungen oder Fehlerberichte zu den Prototypen sind via GitHub Issues willkommen.
• Fokus auf Synthetik: Bitte posten Sie in den Issues oder Diskussionen niemals echte Verwaltungs- oder Bürgerdaten. Verwenden Sie stets anonymisierte oder synthetische Beispieldaten.