harness-template: Vorlage für eine Multi-Agenten-Entwicklungsumgebung mit ausführbaren Abnahmeprüfungen

Summary (English)

harness-template is a template for developing software with language-model agents in which the role that writes the code never accepts it. A Bash orchestrator drives each milestone through fixed phases with separate roles: a builder plans and implements, a reviewer writes executable acceptance tests before implementation and reviews the plan and the code, and an optional QA role searches for reproducible counterexamples. These are roles, not necessarily different models: the operator decides in orchestrator/config.env which command, and thus which model, runs each role. A milestone is completed only when the executable checks selected by the operator (gate scripts such as tests, linting or mutation testing) pass and the reviewer approves; a model verdict alone never suffices, and no model role may write the gate results. After every model call the orchestrator uses Git to verify that the role stayed within its write territory and rolls back violations. Only the human operator changes the specification, and disputes that a fresh arbiter session cannot resolve are parked and handed to the human in an escalation file. A self-test suite with stub models exercises the orchestration logic without calling any model; the documentation below is in German. Version 1.1.0 adds a preset for R packages, an installer for existing repositories and a verified example configuration for three model providers.

Überblick für Außenstehende

Wozu. Die Vorlage ist ein Gerüst, mit dem Sprachmodell-Agenten Software, je nach Preset auch Texte oder Datenpipelines, Meilenstein für Meilenstein bauen, ohne dass die Rolle, die etwas herstellt, es selbst abnimmt. Ein Builder plant und programmiert, ein Reviewer schreibt vorab die Abnahmetests und prüft Plan und Code, eine optionale QA-Rolle sucht reproduzierbare Gegenbeispiele. Das sind Rollen, nicht zwingend verschiedene Modelle: Welches Kommando und damit welches Modell eine Rolle ausführt, legt der Betreiber fest.

Was die Vorlage erzwingt.

Abnahme nur mit bestandenen Prüfungen: Ein Meilenstein ist erst fertig, wenn die vom Betreiber aktivierten Gate-Skripte pass melden und der Reviewer zustimmt; ein Modellurteil allein genügt nie (run_ms in orchestrator/orchestrate.sh, Gate-Lauf in orchestrator/verifier.sh).
Schreibrechte je Rolle und Phase: Nach jedem Modellaufruf prüft der Orchestrator per Git, was sich geändert hat, und verwirft Änderungen außerhalb des Rollenbereichs (path_allowed, ownership_check). Spezifikation, Gate-Auswahl, Meilensteinplan, Konfiguration und Gate-Ergebnisse gehören keiner Modellrolle.
Begrenzte Schleifen: Rundenbudgets, optional ein einmaliger Neuaufbau und eine frische Schiedsrichter-Sitzung; was sie nicht auflöst, wird geparkt und landet als orchestrator/ESCALATION-<MS>.md beim Menschen.

Was sie nicht erzwingt.

verschiedene Modelle oder Anbieter je Rolle; auch der Schiedsrichter läuft über das Reviewer-Kommando,
die Aussagekraft der Prüfungen: Was ein Gate prüft, legt das Projekt fest; ohne aktiviertes Mutations- oder Trace-Gate gibt es diese Prüfungen nicht,
dass jede Entscheidung über den Menschen läuft: Wo die Spezifikation schweigt, legen Reviewer oder Schiedsrichter die Auslegung bindend als ADR fest; Bauregeln, Protokollvertrag und Abnahmetests gehören dem Reviewer,
eine vollständige Abschottung: Alle Rollen laufen unter demselben Benutzer im selben Checkout (Abschnitt 8).

Stand v1.1.1: Umbau der Fassung 1.0.1 für R-Pakete, das Einsetzen in bestehende Repos und eine geprüfte Konfiguration für drei Modellanbieter, dazu die Rundenbindung der Verdicts (Abschnitt 11). Bauplan, zwei anfängliche adversarielle Prüfberichte, Rework und Nachprüfungen des Abnahmestands v1.0 liegen unter docs/template/.

Dieses Template orchestriert drei getrennte Rollen: Ein Builder baut, ein Reviewer prüft und entscheidet, und eine optionale QA-/Red-Team- Rolle sucht reproduzierbare Gegenbeispiele. Unterschiedliche Modellfamilien können über die Rollenkommandos gewählt werden, werden vom Harness aber nicht erzwungen; die effektiven Modellaufrufe kommen aus orchestrator/config.env.

Ein Meilenstein wird nur abgeschlossen, wenn die aktiven Gate-Skripte pass melden und der Reviewer ein PASS ohne blocking-Befunde liefert. Dateien bilden das gemeinsame Gedächtnis. Resume-/Session-Flags sind verboten, und jede Modellphase startet als neuer Prozess. Der Betreiber projektiert und konfiguriert das Vorhaben, startet und beobachtet die Läufe und entscheidet nur dort fachlich nach, wo das Harness eine konkrete Human-Eskalation erzeugt.

Leitprinzip: Prompts erinnern, Gates erzwingen. Specs, Budgets und der Not-Aus bleiben Betreiberentscheidungen.

Alle Pfade in diesem Dokument sind relativ zur Repository-Wurzel. Als Laufzeitpfad oder Projektierungs-Ausgabe gekennzeichnete Ziele werden erst durch bootstrap.sh, die Projektierung oder einen Lauf erzeugt; die jeweils genannte Vorlage beziehungsweise der erzeugende Code ist im Template vorhanden.

Inhalt

Rollen und Territorien
Der Meilenstein-Zyklus
Welche Datei macht was
Neues Projekt: der vollständige Weg
Vorhandenes Material einbringen
Konfiguration
Gates
Sicherheit und ihre Grenzen
Beobachtung und Betrieb
Selbsttest des Templates
Herkunft und Abnahme-Archiv
FAQ
Designphilosophie
Erkenntnisse aus dem Einsatz
Entstehung
Zitieren
Lizenz

1. Rollen und Territorien

Die Produktpfade in der Tabelle entstehen erst im projektierten Zielrepo. Die tatsächlich erzwungene Zuordnung steht in orchestrator/orchestrate.sh; die Rollenregeln stehen in AGENTS.md.

Rolle	Darf schreiben	Darf nicht schreiben	Urteil
Builder	je nach Phase `orchestrator/handoff/<MS>/`; in Build/Rework/Rebuild außerdem `src/`, `tools/`, `tests/unit/`, `tests/properties/`, `public/assets/`, `contracts/api/`, `PROGRESS.md`, `docs/decisions/**`, unterstützte Paketmanifeste und konfigurierte Zusatzpfade	Abnahmetests, Specs, fremde Handoffs und `orchestrator/**` außerhalb der ausdrücklich erlaubten Handoff-Dateien	nein
Reviewer	`tests/acceptance/`, `reference/anchors/`, `orchestrator/handoff/<MS>/`, `IMPLEMENTATION-RULES.md`, `contracts/PROTOCOLS.md`, `BACKLOG.md`, `docs/decisions/` sowie konfigurierte Zusatzpfade; die genaue Menge hängt von der Phase ab	Builder-Nutzlast	`PASS`, `REWORK` oder `ESCALATE`
QA / Red Team	`tests/e2e/`, `tests/fuzz/`, `orchestrator/handoff/<MS>/QA.md`, `BACKLOG.md` sowie konfigurierte Zusatzpfade	alle anderen Pfade	kein Verdict; jeder Befund braucht einen reproduzierbaren Test
Orchestrator	`orchestrator/state/`, `orchestrator/logs/`, maschinelle Handoffs/Eskalationen, `STATUS.md`, Phasencommits und Tags	–	Gate-Ergebnisse, Territorien und Ablaufzustand
Betreiber	Intake und Freigaben, `orchestrator/config.env`, `orchestrator/secrets.env`, `toolchain.json`, Gate-Auswahl und `orchestrator/**`	–	Projektverfassung und Human-Eskalationen

Nach jedem Modellversuch prüft der Orchestrator getrackte und ungetrackte Änderungen, auch an ignorierten Pfaden. Frühere Dateien unter orchestrator/logs/** werden zusätzlich per Hash-Manifest geschützt. Bei einer Territoriumsverletzung wird der Versuch zurückgerollt und genau einmal mit Hinweis wiederholt; die zweite Verletzung endet mit FATAL/Exit 2.

Die regulären Build-/Laufzeitartefakte in orchestrator/artifact-paths.allowlist, etwa dist/, reports/ und node_modules/, sind von der Territoriumsprüfung ausgenommen. Diese Ausnahme ist bewusst weit: Sie ist keine inhaltliche Prüfung der Artefakte.

Für fachlichen Dissens gilt Spec > Reviewer > Builder. Deckt kein Spec-Zitat die Builder-Position, bindet nach Ende der Verhandlung das Reviewer-Urteil und wird als ADR dokumentiert; widersprüchliche Specs führen zur Eskalation.

2. Der Meilenstein-Zyklus

Die implementierte Reihenfolge in orchestrator/orchestrate.sh lautet:

PREFLIGHT
  → ACCEPTANCE
  → PLAN ↔ PLAN-REVIEW
  → BUILD
  → GATES
  → optional QA
  → bei ausgeführter QA: GATES erneut
  → CODE-REVIEW
      ├─ Gates pass + Reviewer PASS → DONE
      └─ sonst REWORK → nächste Runde ab GATES

Derselbe Ablauf als Diagramm, mit Rollen, Gates und den Stellen, an denen der Mensch entscheidet:

flowchart TD
    OP["Betreiber: Spezifikation freigeben,<br/>Gates wählen, konfigurieren, committen"]
    PRE["PREFLIGHT<br/>Orchestrator"]
    ACC["10 ACCEPTANCE<br/>Reviewer: Kriterien und Abnahmetests"]
    PLAN["20 PLAN<br/>Builder"]
    PREV{"30 PLAN-REVIEW<br/>Reviewer"}
    BUILD["40 BUILD<br/>Builder"]
    GATES["GATES<br/>verifier.sh führt die Gate-Skripte aus"]
    QA["45 QA, optional<br/>Gegenbeispiele als Tests,<br/>danach GATES erneut"]
    CREV{"50 CODE-REVIEW<br/>Reviewer"}
    DONE["DONE<br/>PROGRESS.md geändert, Tag done/MS"]
    FIX["60 REWORK, später einmal 62 REBUILD<br/>Builder"]
    ARB{"70 ARBITER<br/>frische Reviewer-Sitzung,<br/>einmal je Meilenstein"}
    PARK["PARK<br/>ESCALATION-MS.md, Benachrichtigung"]
    HUMAN["Mensch entscheidet und<br/>entfernt den Parkmarker"]

    OP --> PRE --> ACC --> PLAN --> PREV
    PREV -->|PASS| BUILD
    PREV -->|REWORK| PLAN
    PREV -->|ESCALATE oder Planbudget erschöpft| ARB
    BUILD --> GATES
    GATES -->|QA aktiv und fällig| QA
    QA --> CREV
    GATES --> CREV
    CREV -->|PASS und Gates pass| DONE
    CREV -->|sonst| FIX
    CREV -->|ESCALATE oder Rundenbudget erschöpft| ARB
    CREV -->|nur Gate-error, nach Wiederholungen| PARK
    FIX --> GATES
    ARB -->|RESOLVE im Planstreit| PLAN
    ARB -->|RESOLVE im Codestreit, Zusatzrunden| FIX
    ARB -->|HUMAN oder schon verbraucht| PARK
    PARK --> HUMAN
    HUMAN -.->|Neustart, Wiederaufnahme| PRE

    classDef human stroke-width:3px,stroke-dasharray:6 4
    class OP,PARK,HUMAN human

Gestrichelt umrandet sind die Stellen, an denen der Mensch entscheidet. Der Schiedsrichter ist ein Modell: Sein RESOLVE ist bindend und braucht keinen Betreiberentscheid. Aus dem Schiedsverfahren führen nur HUMAN oder ein erneuter Schiedsfall (ESCALATE oder erschöpftes Rundenbudget) im selben Meilenstein zum Park. Nicht eingezeichnet sind die Territoriumsprüfung nach jedem Modellaufruf (Verstoß: Rollback, eine Wiederholung, danach FATAL/Exit 2) sowie FATAL-Abbrüche, STOP und fehlende Pflicht-QA; auch diese Fälle landen beim Betreiber.

PREFLIGHT prüft Git-Identität, Manifest und Dependency-Zyklen, Vertragspfade, Toolchain-Versionen, reale CLI-Hilfen und konfigurierte Sicherheitsflags. Getrackte oder nicht ignorierte Git-Änderungen außerhalb der ausdrücklich tolerierten Status-, STOP-, Summary- und Lockpfade machen den Arbeitsbaum FATAL; regulär ignorierte Artefakte erscheinen in dieser PREFLIGHT-Prüfung nicht.
ACCEPTANCE lässt den Reviewer vor der Implementierung orchestrator/handoff/<MS>/CRITERIA.json und ausführbare Tests unter tests/acceptance/** schreiben. Rot ist in dieser Phase erwartet; der Orchestrator führt hier selbst noch kein Testkommando aus.
PLAN/PLAN-REVIEW verhandeln über stabile Einwand-IDs. Der Default sind höchstens zwei Planrunden (MAX_ROUNDS_PLAN=2); die Konfiguration kann den Wert ändern.
Verdicts gelten nur für ihre Runde: Nach PLAN-REVIEW und CODE-REVIEW liest der Orchestrator verdict-plan.json beziehungsweise verdict-code.json nur, wenn round der laufenden Runde entspricht. Fehlt das Verdict oder stammt es aus einer früheren Runde, endet der Lauf mit FATAL; ein liegengebliebenes Verdict entscheidet nie über neuen Code (RUNBOOK, FATAL).
GATES führt alle ausführbaren Dateien mit dem Muster orchestrator/gates.d/NN-*.sh aus und schreibt den Laufzeitpfad orchestrator/state/<MS>/gates.json. Ohne aktives Gate lautet das Ergebnis error.
QA läuft nach dem ersten nicht rein infrastrukturell fehlgeschlagenen Gate-Lauf, wenn QA_ENABLED=1. Danach werden die Gates erneut ausgeführt. Standardmäßig läuft QA einmal pro Meilenstein; eine Datei orchestrator/state/<MS>/qa-requested fordert einen weiteren QA-Lauf an.
Leiter: Wenn LADDER_ENABLED=1, setzt der Orchestrator ab REBUILD_ROUND einmal die in REBUILD_PATHS genannten Builder-Pfade auf plan/<MS> zurück und ruft Prompt 62 auf. Bei ESCALATE oder verbrauchtem Rundenbudget entscheidet einmal eine frische Arbiter-Session. RESOLVE gibt ARBITER_EXTRA_ROUNDS Zusatzrunden; HUMAN parkt den Meilenstein.
PARK & CONTINUE schreibt orchestrator/ESCALATION-<MS>.md, orchestrator/ESCALATION.md und den Laufzeitmarker orchestrator/state/<MS>/parked. Danach werden weitere Meilensteine mit erfüllten Abhängigkeiten geprüft. Der Marker wird mit dem Park-Commit versioniert.
DONE verlangt zusätzlich, dass PROGRESS.md seit plan/<MS> geändert wurde, und erzeugt den unveränderlich behandelten Tag done/<MS>.

Exit-Codes von orchestrator/orchestrate.sh:

0: Lauf regulär beendet oder die konfigurierte Autonomiegrenze wurde planmäßig erreicht.
2: FATAL, zum Beispiel PREFLIGHT-, Transport-, Rollen-, Commit- oder Vertragsfehler.
3: Lauf beendet und mindestens ein Meilenstein ist geparkt; dazu zählt auch ein dauerhaft reiner Gate-Infrastrukturfehler.

3. Welche Datei macht was

Repository-Wurzel

Datei	Zweck
`AGENTS.md`	Verfassung: Rollen, Territorien, acht Integritätsregeln, Handoff-Disziplin und auszufüllender Projektblock
`CLAUDE.md`	Kompatibilitätszeiger auf `AGENTS.md`
`IMPLEMENTATION-RULES.md`	verbindliche Bauregeln im Reviewer-Territorium
`contracts/PROTOCOLS.md`	Phasen-, Verdict-, Gate-, Status-, Provenienz-, Anker- und Toolchain-Vertrag
`contracts/api/README.md`	Vertrag für projektbezogene Public-API-Snapshots
`BACKLOG.md`	nonblocking Befunde und vertagte Punkte; spätere Pläne müssen sie adressieren oder begründet vertagen
`PROGRESS.md`	Langzeitgedächtnis des Builders; eine Änderung seit `plan/<MS>` ist DONE-Bedingung
`RUNBOOK.md`	Handgriffe für PARKED, HUMAN, FATAL, STOP, Locks, Tunnel und Watchdog
`bootstrap.sh`	prüft Core-Werkzeuge und Git-Identität, erzeugt lokale Konfiguration/Secrets, installiert oder prüft Toolchain und MCP-Umgebung, prüft den Statusvertrag und startet standardmäßig MCP plus Tunnel in tmux
`start.sh`	prüft minimale Voraussetzungen und ersetzt sich im Vordergrund durch `orchestrator/orchestrate.sh`; es erzeugt keine tmux-Session und führt keine eigene Transportprobe aus
`config.env.example`	versionierte Vorlage; `bootstrap.sh` kopiert sie in den ungetrackten Laufzeitpfad `orchestrator/config.env` und setzt Modus 600
`toolchain.json.example`	leere Vertrag-v1-Vorlage; `bootstrap.sh` kopiert sie bei Bedarf in den ungetrackten Laufzeitpfad `toolchain.json`
`docs/00-vision.md.template`	Vorlage, die im Zielprojekt durch die freigegebene Vision ersetzt wird
`docs/decisions/ADR-000-vorlage.md`	ADR-Vorlage
`docs/template/`	Bau-, Rework- und Abnahme-Archiv des Templates; Zielprojekte dürfen diesen gesamten Ordner löschen
`reference/`	vorhandene Wurzel für Projektquellen
`reference/anchors/README.md`	Schema für projektbezogene Ankerdateien unter `reference/anchors/*.json`; das unveränderte Template enthält noch keinen normativen JSON-Anker
`tools/install-into.sh`	setzt die Harness-Teile in ein bestehendes Git-Repo ein (Abschnitt 5); Werkzeug des Templates, das selbst nicht mitkopiert wird

bootstrap.sh akzeptiert genau die Flags --update, --non-interactive, --no-start und --edit. --update verwendet vorhandene updateCommand-Einträge aus toolchain.json und fällt sonst auf das jeweilige installCommand zurück; --no-start überspringt MCP und Tunnel.

`orchestrator/`

Datei	Zweck
`orchestrator/orchestrate.sh`	Lock, PREFLIGHT, Phasenschleife, Rollenaufrufe, Retries, Territorien, Commits, Tags, Rebuild, Arbiter und Park-&-Continue
`orchestrator/verifier.sh`	Gate-Runner für ausführbare `orchestrator/gates.d/NN-*.sh`
`orchestrator/gates.d/README.md`	kurze Aktivierungsanleitung für Gate-Beispiele
`orchestrator/gates.d/_lib.sh`	gemeinsame Funktionen für konfigurierte Kommando-Gates
`orchestrator/lib/toolchain.sh`	prüft und installiert die in `toolchain.json` deklarierten Laufzeiten und Manifeste
`orchestrator/lib/r-deps.R`, `r-tests.R`, `r-check.sh`, `r-mutation.R`	Gate-Kommandos des Presets `r-paket`: Abhängigkeiten, ein testthat-Lauf über alle Rollen-Testordner, `R CMD build`/`check --as-cran` außerhalb des Repos, muttest-Adapter für `86-mutgate`
`orchestrator/policies/qa-gemini.toml`	Policy der Gemini CLI für die QA-Rolle: als einziges Shell-Kommando `Rscript`
`orchestrator/status.sh`	schreibt `STATUS.md` und `orchestrator/state/summary.json` nach Statusvertrag v1
`orchestrator/notify.sh`	best-effort HTTP-POST für `FATAL`, `PARKED`, `ARBITER`, `NEEDS_HUMAN`, `DONE` und `STALE`
`orchestrator/watchdog.sh`	meldet `STALE`, wenn eine Lock-PID lebt und der Summary-Heartbeat zu alt ist
`orchestrator/milestones.json.example`	Manifestvorlage; `bootstrap.sh` erzeugt daraus bei Bedarf die projektbezogene Datei `orchestrator/milestones.json`
`orchestrator/prompts/10-acceptance.md` bis `orchestrator/prompts/70-arbiter.md`	neun Phasenprompts: 10, 20, 30, 40, 45, 50, 60, 62 und 70; jeder enthält ein Kontextmanifest
`orchestrator/handoff/SCHEMA.md`	Schema für Plan, Review, Verdicts, Arbiter und Mutation-Äquivalenz
`orchestrator/handoff/<MS>/`	Laufzeitpfad für meilensteinbezogene Rollenübergaben
`orchestrator/state/<MS>/`	Laufzeitpfad für Gates, Phasenmarker, Runde und Parkzustand
`orchestrator/logs/`	lokale Laufzeitlogs und Promptarchive
`orchestrator/artifact-paths.allowlist`	Regex-Liste territoriumsfreier Build-/Laufzeitartefakte
`orchestrator/mcp/server.py`	MCP-Connector mit den Tools `lies`, `liste`, `befehl` und `lessons_schreiben`; die drei ersten sind lesend, das letzte ist der einzige Schreibpfad
`orchestrator/mcp/tests/test_allowlist.py`	ausführbare Allowlist-Abnahme mit aktuell 72 Fällen
`orchestrator/LESSONS.md`	kuratiertes Destillat; `lessons_schreiben` ersetzt die Datei vollständig und akzeptiert höchstens 16.000 Zeichen

Modelltranskripte heißen <MS>-<phase>-r<runde>-a<versuch>-<zeitstempel>.log. Das einmal pro Phasenaufruf gerenderte Promptarchiv heißt <MS>-<phase>-r<runde>-<zeitstempel>-prompt.md; QA-Routenproben verwenden ein eigenes qa-probe-<zeitstempel>-<versuch>.md-Muster. Die Prompts 20, 30, 40, 50, 60 und 62 lesen orchestrator/LESSONS.md, wenn die Datei vorhanden ist.

`projektierung/`

Datei	Zweck
`projektierung/PROJEKTIERUNG.md`	eigenständiges Playbook für zehn logische Projektierungs-Ausgaben; bei Intake-Lücken verlangt es Rückfragen statt Annahmen
`projektierung/INTAKE-CHECKLISTE.md`	acht Pflichtfelder des Betreiber-Inputs
`projektierung/SPEC-KONTRAKT.md`	Format für Specs, Kriterien, Traceability, Meilensteine, Anker und ADRs
`projektierung/presets/software-ts/PRESET.md`	TypeScript-Layout, Gate-Grundsätze und Zusatzterritorien
`projektierung/presets/text/PRESET.md`	Manuskript-Layout, Text-Gates und Zusatzterritorien
`projektierung/presets/daten/PRESET.md`	Datenpipeline-Layout, Daten-Gates und Zusatzterritorien
`projektierung/presets/r-paket/PRESET.md`	R-Paket: Territorien, Toolchain, R-Gates, muttest, `.Rbuildignore`, pkgdown und `docs/`, Quellen, Einsetzen in ein bestehendes Paket; die markierten Konfigurationsblöcke fährt T-10 aus
`projektierung/beispiel/README.md`	Einordnung des gekürzten Demiurg-Beispiels unter `projektierung/beispiel/demiurg/`

`tests/template/`

tests/template/run-all.sh fährt die Selbsttests des Templates. Diese Tests gehören zur Template-Abnahme, nicht zu den späteren Produkttests eines Zielprojekts.

4. Neues Projekt: der vollständige Weg

Schritt 0: Besprechen. Das Destillat wird gegen projektierung/INTAKE-CHECKLISTE.md geführt. Die acht Felder sind: Vision, Zielgruppe/Nutzungskontext, Out-of-Scope, Stack/Format samt Laufzeiten, messbarer Qualitätsmaßstab je Kernfeature, Quellen/Originale, Risiken und offene Fragen sowie Rollen/Budget.

Schritt 1: Projektieren. Gib das Destillat zusammen mit projektierung/PROJEKTIERUNG.md, projektierung/INTAKE-CHECKLISTE.md, projektierung/SPEC-KONTRAKT.md und genau einem passenden projektierung/presets/*/PRESET.md in eine Projektierungs-Session. Bei Lücken soll die Session stoppen und gesammelt nachfragen. Entschiedenes wandert in die Spec, offen Erwogenes in den Katalog, Verworfenes in Out-of-Scope.

Schritt 2: Redigieren. Lies zuerst die erzeugte Projektierungs-Ausgabe OFFENE-PUNKTE.md, dann Specs und Kriterien. Erst die Betreiberfreigabe verleiht Spec-Rang.

Schritt 3: Klonen und Ausgaben einsetzen. Der konfigurierte Remote dieses Repos lautet derzeit:

git clone https://github.com/DanielMoj/harness-template.git mein-projekt
cd mein-projekt

Die folgende Tabelle nennt Projektierungs-Ausgaben; diese Dateien sind nicht als fertige Projektspezifikation im neutralen Template eingecheckt.

Projektierungs-Ausgabe	Ziel im Klon
`docs/00-vision.md`	ersetzt `docs/00-vision.md.template`
`docs/01-fachspezifikation.md` und gegebenenfalls weitere nummerierte Specs	unter `docs/`
`docs/90-katalog-offen.md`	unter `docs/`
`orchestrator/milestones.json`	ersetzt die von `orchestrator/milestones.json.example` abgeleitete Laufzeitdatei
`AGENTS-PROJEKTBLOCK.md`	Inhalt in den Projektblock von `AGENTS.md` übernehmen
`gates-auswahl.md`	Betreiber-Arbeitsdatei für die Gate-Aktivierung; der Orchestrator liest sie nicht automatisch
`ANKER-TODO.md`	Arbeitsliste für die spätere Reviewer-Erhebung unter `reference/anchors/`; der Orchestrator liest sie nicht automatisch
`BACKLOG-START.md`	Inhalt nach `BACKLOG.md` übernehmen
`toolchain-entwurf.json`	als `toolchain.json` übernehmen
`OFFENE-PUNKTE.md`	Betreiber-Arbeitsdatei; vor Freigabe abarbeiten

Schritt 4: Bootstrap. bash bootstrap.sh erzeugt bei Bedarf orchestrator/config.env, orchestrator/secrets.env, toolchain.json und orchestrator/milestones.json. Es installiert beziehungsweise prüft die deklarierte Toolchain und das externe MCP-venv, führt MCP-Selbsttest und Statusprüfung aus und startet standardmäßig MCP plus Cloudflare-Tunnel in einer tmux-Session. Danach druckt es die Connector-URL. Für einen Lauf ohne Server/Tunnel dient bash bootstrap.sh --no-start. Beim ersten Lauf öffnet es orchestrator/config.env mit ${EDITOR:-vi} und fragt auch mit --no-start nach dem Tunnelmodus. Ohne Rückfragen läuft bash bootstrap.sh --no-start --non-interactive (kein Editor, Tunnelmodus quick); orchestrator/config.env danach bearbeiten. Wer interaktiv startet, setzt etwa EDITOR=nano.

Schritt 5: Konfigurieren. Fülle orchestrator/config.env. Die effektiven Rollenaufrufe stehen in BUILDER_CMD, REVIEWER_CMD und gegebenenfalls QA_CMD.

Aktiviere nur benötigte Gates. Kopieren allein genügt nicht, weil die eingecheckten Beispiele Modus 644 haben; die Kopie muss ausführbar werden:

cp orchestrator/gates.d/30-tests.sh.example orchestrator/gates.d/30-tests.sh
chmod +x orchestrator/gates.d/30-tests.sh
git add --chmod=+x orchestrator/gates.d/30-tests.sh

git add --chmod=+x ist nötig, wo Git core.filemode=false verwendet, etwa auf /mnt/c unter WSL: Ein gewöhnliches git add trägt neue Dateien dort als 100644 ein, und ein frischer Klon hätte nicht ausführbare Gates, die orchestrator/verifier.sh nicht aktiviert. git ls-files -s orchestrator/gates.d/[0-9][0-9]-*.sh zeigt den Modus; jede Zeile beginnt mit 100755. core.filemode bleibt auf /mnt/c false, sonst erscheint jede Datei als geändert.

Schritt 6: Vorwissen platzieren. Siehe Abschnitt 5.

Schritt 7: Projektstand committen. Vor dem Orchestratorstart müssen Specs, AGENTS.md, orchestrator/milestones.json, aktivierte Gate-Skripte und alle anderen nicht ignorierten Projektierungs-Ausgaben in einem Betreiber-Commit stehen oder bewusst außerhalb des Checkouts liegen. PREFLIGHT lehnt einen nicht sauberen Arbeitsbaum ab; die lokale orchestrator/config.env, orchestrator/secrets.env und toolchain.json sind davon wegen der Ignore-Regeln ausgenommen.

Schritt 8: M0 starten. bash start.sh M0 und bash orchestrator/orchestrate.sh M0 laufen beide im Vordergrund. Für eine eigene tmux-Session muss der Betreiber den Befehl selbst in tmux starten. M0 wird von projektierung/PROJEKTIERUNG.md und projektierung/SPEC-KONTRAKT.md als Gerüst-/Toolchain-/Leere-Gates- Meilenstein vorgegeben; der Orchestrator besitzt dafür keinen Sonderfall. Ohne Ziel-ID verarbeitet bash start.sh die Queue nur bis zur Grenze von MAX_MS_PER_RUN.

Schritt 9: Beobachten. Konfiguriere NOTIFY_URL; richte den Watchdog separat nach RUNBOOK.md als Cronjob ein. Benachrichtigungen sind best-effort und hängen außerdem von NOTIFY_ENABLED ab.

Schritt 10: Eingreifen mit Beleg. Bei PARKED zuerst orchestrator/ESCALATION-<MS>.md, Handoff und Gate-Logs lesen. Nach Behebung der Ursache den Laufzeitmarker mit git rm orchestrator/state/<MS>/parked entfernen, committen und neu starten; nach einem bloßen rm lehnt der PREFLIGHT den Arbeitsbaum als unsauber ab. touch orchestrator/STOP führt vor der nächsten geprüften Phase zu FATAL/Exit 2; anschließend muss die STOP-Datei für die Wiederaufnahme entfernt werden.

5. Vorhandenes Material einbringen

Das Projektierungs-Playbook verlangt vollständiges Sortieren statt stilles Kürzen. Es ist eine Prompt-Regel, kein maschineller Beweis dafür, dass eine Projektierungs-KI tatsächlich nichts ausgelassen hat; die Betreiberredaktion bleibt nötig.

Vorhandenes Material	Ablage/Verarbeitung	Tatsächlicher Harness-Bezug
KI-Besprechungen, Notizen, Ideenlisten	ungekürzt an das Intake anhängen	`projektierung/PROJEKTIERUNG.md` verlangt die Sortierung entschieden/offen/verworfen
Konzepte und Spezifikationen	Original unter `reference/` behalten und dem Intake beilegen	freigegebener bindender Inhalt wird als nummerierte Spec unter `docs/` projektiert
eigene Agentenregeln	nicht als zweite Verfassung parallel führen	Bauregeln nach `IMPLEMENTATION-RULES.md`, Projektfakten in den Projektblock von `AGENTS.md`, Quellenwissen nach `reference/`
bestehender Code	als Vorlage unter einem in der Spec benannten Unterordner von `reference/` ablegen oder das Harness direkt in das bestehende Repo einsetzen (unten)	Portierung kann als früher Meilenstein mit Differentialtests geplant werden; `tools/install-into.sh` setzt das Harness in ein bestehendes Repo ein, ohne dessen Dateien zu überschreiben
urheberrechtlich geschützte Literatur	nur der Textspiegel unter `reference/quellen/` (git-ignoriert), der Katalog versioniert als `reference/QUELLENKATALOG.md`; PDFs, EPUB und Rohdaten außerhalb des Repos	die Territoriumsprüfung erfasst auch ignorierte Dateien; jede Datei im Checkout verlängert jeden Modellaufruf (Messwerte im Preset `r-paket`, Abschnitt Quellen)
Daten, CSVs, Medien	unter `reference/` oder einem in der Spec benannten Projektpfad	die mitgelieferten Asset-/Daten-Gates führen nur konfigurierte Befehle aus; Manifest- oder SHA256-Prüfungen müssen im jeweiligen Projektkommando tatsächlich implementiert sein
Zahlen, Grenzwerte, Messlatten	Quellen in Intake-Feld 6 und der Projektierungs-Ausgabe `ANKER-TODO.md`	der Reviewer soll daraus projektbezogene `reference/anchors/*.json` nach `reference/anchors/README.md` erstellen
Stil-, Figuren- oder Weltbibel	Pfade gemäß `projektierung/presets/text/PRESET.md`	Freigabe über `REVIEWER_EXTRA_PATHS_REGEX`; konkrete Prüfkommandos kommen aus der Projektkonfiguration
bestehende Tests	als Quellenmaterial oder später im passenden Projektterritorium	Abnahmetests unter `tests/acceptance/**` schreibt der Reviewer neu aus freigegebenen Kriterien

Harness in ein bestehendes Repo einsetzen

Statt eines frischen Klons kann das Harness in ein vorhandenes Repo kommen:

bash tools/install-into.sh --dry-run <zielrepo>              # nur anzeigen
bash tools/install-into.sh [--katalog <KATALOG.md>] <zielrepo>

Das Skript kopiert die Harness-Teile aus dem Index des Templates und überschreibt nie Projektdateien: README.md, LICENSE, LICENSE.md, CITATION.cff und .zenodo.json bleiben unangetastet, vorhandene Dateien mit anderem Inhalt (etwa ein eigenes AGENTS.md) bleiben und erscheinen als Konflikt im Bericht. .gitignore und .gitattributes werden zusammengeführt, nicht ersetzt; .gitignore erhält dabei reference/quellen/. Bei einem R-Paket ergänzt es .Rbuildignore um die Harness-Dateien. Template-Interna (docs/template/, tests/template/, tools/, der Verlauf in PROGRESS.md) kommen nicht mit; PROGRESS.md entsteht als leeres Gerüst. Jede Datei mit Modus 100755 im Template wird mit git add --chmod=+x eingetragen. Das Skript staged nur; den Commit macht der Betreiber. Es verlangt einen sauberen Arbeitsbaum und endet mit Exit 0 (eingesetzt), 3 (eingesetzt, offene Punkte im Bericht, etwa ein ignoriertes docs/ oder pkgdown nach docs/) oder 2 (nichts geändert). Die Schritte danach beschreibt projektierung/presets/r-paket/PRESET.md, Abschnitt „Einsetzen in ein bestehendes Paket“; für andere Stacks gelten sie sinngemäß.

6. Konfiguration

Die vollständige Variablenliste und Defaults stehen in config.env.example; die wirksame, ungetrackte Datei ist orchestrator/config.env.

Rollenaufrufe und Wächter

Die ausführbaren Kommandos heißen exakt BUILDER_CMD, REVIEWER_CMD und QA_CMD. In diesen Strings ist $PROMPT_FILE beziehungsweise ${PROMPT_FILE} die einzige zulässige Shell-Variablenreferenz.
BUILDER_HELP_CMD, REVIEWER_HELP_CMD und QA_HELP_CMD werden im PREFLIGHT wirklich ausgeführt. Die zu suchenden Flags stehen in BUILDER_REQUIRED_FLAGS, REVIEWER_REQUIRED_FLAGS und QA_REQUIRED_FLAGS; die effektiven sicheren Modi werden mit BUILDER_SAFE_MODE_PATTERN, REVIEWER_SAFE_MODE_PATTERN und QA_SAFE_MODE_PATTERN geprüft.
ROLE_GUARDS=off ist der einzige bewusste Abschalter für leere Required-/Safe-Mode-Prüfungen und wird in Log und Summary sichtbar. Die Verbotslisten für Rollenkommandos bleiben trotzdem aktiv; FATAL nennt das gefundene Muster:
- Resume: --continue, --resume, --session, --session-file und die Unterkommandos resume und fork (etwa codex exec resume --last),
- Bypass und Full Access: alles mit dangerously-skip, dangerously-bypass oder dangerously-disable (darunter --dangerously-skip-permissions, --allow-dangerously-skip-permissions, --dangerously-bypass-approvals-and-sandbox), bypassPermissions, --yolo, full-access (auch danger-full-access),
- Yolo- und Klassifikator-Freigaben: --approval-mode yolo und --approval-mode=yolo (Gemini CLI, Qwen Code), --approval-mode auto (Qwen Code: ein LLM-Klassifikator entscheidet), --permission-mode auto (Claude Code) und --approve-for-me (Codex CLI).
Die sicheren Bearbeitungsmodi --approval-mode auto_edit (Gemini CLI) und --approval-mode auto-edit (Qwen Code) bleiben erlaubt. Kurzflags wie -y, -c oder -r bedeuten je CLI Verschiedenes (-c ist bei Codex --config) und stehen deshalb nicht auf der Liste; Freigaben in CLI-Einstellungsdateien sieht der Wächter ebenfalls nicht (Abschnitt 8).
Die strikte QA-Routenprobe schreibt die vollständige CLI-Ausgabe nach orchestrator/logs/qa-probe-<zeitstempel>-<versuch>.log; orchestrator/logs/orchestrate.log nennt den Pfad. So wird etwa eine stille Rückstufung des Freigabemodus sichtbar (RUNBOOK, PREFLIGHT).
BUILDER_MODEL, REVIEWER_MODEL, QA_MODEL und QA_ENDPOINT in der Vorlage steuern den Modellaufruf nicht. QA_MODEL erscheint nur als Bezeichnung im erfolgreichen QA-Probe-Log; die übrigen drei werden vom Orchestrator nicht ausgewertet. Modell und Endpoint müssen daher in BUILDER_CMD, REVIEWER_CMD beziehungsweise QA_CMD wirksam konfiguriert werden.

Beispiel: drei Anbieter

config.env.example enthält einen auskommentierten, am 23.10.2026 geprüften Block: Builder GPT-6 Astra über Codex CLI 0.164.0, Reviewer und Schiedsrichter Claude Opus 5.5 über Claude Code 2.1.309, QA Gemini 4 Argon über Gemini CLI 0.65.0 (Weg A) mit Kimi K3 über Qwen Code 0.26.0 als Ersatz (Weg C). Alle Flags stehen im echten --help der genannten Versionen; ein PREFLIGHT mit diesem Block, den echten CLIs und der QA-Routenprobe ohne Terminal ist bestanden (Beleg in PROGRESS.md).

Effort: claude --effort max und codex exec -c model_reasoning_effort=max. Codex nimmt einen -c-Wert, der kein gültiges TOML ist, als Rohstring. ultra delegiert bei Codex automatisch an Unteragenten und wird nicht verwendet. Der Schiedsrichter läuft über REVIEWER_CMD und erhält dieselbe Stufe (Selbsttest T-3).
Modellnamen: codex debug models zeigt den Codex-Katalog, gpt-6-astra steht dort auch ohne Anmeldung; einen Befehl codex models gibt es in 0.164.0 nicht. Die Freischaltung für das Konto belegt nur ein echter Aufruf. Die API-Kennung von Gemini 4 Argon ist gemini-4-argon (stabile Kennung laut Gemini-API-Dokumentation); die Gemini CLI kennt das Modell nicht aus ihrer eingebauten Liste und reicht die Kennung durch.
Anmeldung: Rollen laufen mit env -i; Schlüssel als Umgebungsvariable kommen nicht an. Jede CLI muss unter HOME angemeldet sein: Codex über codex login, Claude Code über die Browser-Anmeldung, die Gemini CLI über ~/.gemini/.env, Qwen Code über ~/.qwen/.env.
Netz: Codex --sandbox workspace-write hat kein Netz (Sitzungsdaten: network_access: false); Abhängigkeiten installiert das deps-Gate vorab, außerhalb der Sandbox.
WSL2/Linux: Codex braucht bubblewrap (bwrap), die Gemini CLI ripgrep.
Shell für QA und Reviewer: nur Rscript, über die Gemini-Policy orchestrator/policies/qa-gemini.toml, bei Qwen Code über --allowed-tools, beim Reviewer über --allowedTools "Bash(Rscript:*)". Das ist keine Sicherheitsgrenze (Abschnitt 8).
Gemini CLI und Ordner-Vertrauen: ~/.gemini/.env wird nur in vertrauten Ordnern gelesen, und in nicht vertrauten Ordnern stuft die CLI --approval-mode auto_edit still auf default zurück. Abhilfe: security.folderTrust.enabled=false in ~/.gemini/settings.json oder das Zielrepo in ~/.gemini/trustedFolders.json.

Autonomie

Die Stufen setzen Defaults; explizite nichtleere Werte für MAX_MS_PER_RUN, LADDER_ENABLED und NOTIFY_ENABLED überschreiben sie.

`AUTONOMY_LEVEL`	Defaults im Orchestrator
0	genau ein Phasencommit pro Aufruf; `MAX_MS_PER_RUN=1`, Leiter und Notify aus
1	höchstens ein Meilenstein pro Aufruf; Leiter und Notify aus
2	höchstens vier Meilensteine pro Aufruf; Leiter und Notify an; Vorlagen-Default
3	höchstens 999 Meilensteine pro Aufruf; Leiter und Notify an

Stufe 3 installiert keinen Timer. Zeit- oder Nachtstarts müssen extern, etwa über cron oder systemd, eingerichtet werden. Ein explizites Ziel wie bash start.sh M0 beschränkt den Lauf unabhängig von der Stufe auf diesen Meilenstein.

QA, Budgets und Betrieb

QA: QA_ENABLED, QA_REQUIRED_FROM, QA_PROBE_STRICT, QA_PROBE_RETRIES, QA_PROBE_TIMEOUT, QA_PROBE_SLEEP. Ist QA ab einer Manifest-ID Pflicht, aber QA_ENABLED nicht 1, wird der Meilenstein vor der Rework-Schleife geparkt.
Verhandlung/Leiter: MAX_ROUNDS_PLAN, MAX_ROUNDS_REWORK, REBUILD_ROUND, ARBITER_EXTRA_ROUNDS, LADDER_ENABLED.
Transport/Gates: PHASE_TIMEOUT, RETRY_MAX, RETRY_SLEEP, GATE_ERROR_RETRIES, MAX_MS_PER_RUN.
Zusatzterritorien: BUILDER_EXTRA_PATHS_REGEX, REVIEWER_EXTRA_PATHS_REGEX, QA_EXTRA_PATHS_REGEX; der Rebuild-Umfang steht in REBUILD_PATHS.
Rollen-Umgebung: BUILDER_ENV_ALLOWLIST, REVIEWER_ENV_ALLOWLIST, QA_ENV_ALLOWLIST. Namen mit API_KEY, TOKEN, SECRET, PASSWORD oder PRIVATE_KEY werden abgelehnt.
Benachrichtigungen: NOTIFY_ENABLED schaltet den Versand, NOTIFY_URL ist die vollständige POST-Zieladresse und NOTIFY_TOPIC wird nur als Präfix des HTTP-Title-Headers verwendet.
GATE_ERROR_CODES ist eine globale Liste für die mit gate_run_configured ausgeführten Kommando-Gates. Sie ist keine gate-spezifische Zuordnung.

7. Gates

orchestrator/verifier.sh aktiviert ausschließlich ausführbare Dateien, die orchestrator/gates.d/NN-*.sh entsprechen. Es exportiert unter anderem REPO_ROOT, ORCH, MILESTONE, ROUND, BASE_SHA, GATE_ARTIFACT_DIR und GATES_PROGRESS_JSON.

Der Steckplatzvertrag ist:

Exit 0 → pass
Exit 1 → fail
Exit 2 → error
jeder andere Exit-Code → error mit Runner-Hinweis
letzte nichtleere stdout-Zeile → Kurzbefund
vollständiges stdout/stderr → orchestrator/state/<MS>/gate-<name>.log
Aggregat → orchestrator/state/<MS>/gates.json

Enthält ein Lauf mindestens ein fail, ist sein Aggregat fail, auch wenn zugleich ein Gate error meldet. Ohne fail, aber mit mindestens einem error, ist es error.

orchestrator/gates.d/_lib.sh behandelt bei gate_run_configured standardmäßig rc 126 und 127 als Infrastrukturfehler; andere rc größer 0 werden fail. GATE_ERROR_CODES ersetzt diese globale Liste.

Ein reines Gate-Aggregat error verbraucht keine Rework-Runde und löst keinen Rebuild aus. Mit dem Default GATE_ERROR_RETRIES=2 folgen auf den ersten Lauf zwei Wiederholungen in derselben Runde; bleibt das Ergebnis error, wird der Meilenstein mit Exit 3 geparkt. Ein gemischter Fail/Error-Lauf folgt dagegen dem normalen Rework-Pfad.

Mitgelieferte Beispiele

Die einfachen Wrapper delegieren das fachliche Urteil an das jeweils konfigurierte Kommando: 10-deps, 20-lint, 30-tests, 40-smoke, 50-graph, 60-api, 80-bench, 81-e2e, 83-assets, 84-shots, 85-research, 91-stil-lint, 93-zitate, 94-schema, 95-repro und 96-golden. 84-shots legt vorher zusätzlich das Gate-Artefaktverzeichnis an. Ein leerer Kommandowert ergibt error; die Wrapper implementieren nicht selbst die fachliche Prüfung.

Besondere Logik besitzen:

orchestrator/gates.d/70-trace.sh.example: Ohne TRACE_CMD prüft es orchestrator/handoff/<MS>/CRITERIA.json, wörtliche Spec-Zitate und Manifest-IDs. Jedes dort geführte Kriterium muss irgendwo unter tests/acceptance/** referenziert sein; jede dort gefundene ID im Muster <Buchstabe>-<MS>-<Zahl> muss in derselben Kriterien-Datei bekannt sein. Es prüft weder, ob jede einzelne Testdatei eine ID trägt, noch eine Zuordnung von Gates zu Kriterien.
orchestrator/gates.d/82-territory.sh.example: prüft, dass der letzte Territoriums-Audit zur aktuellen Runde und Basis passt.
orchestrator/gates.d/86-mutgate.sh.example: berechnet einen Mutation-Score aus einem Report im Stryker-Schema, nutzt Floor/Ratchet/Baseline und meldet einen fehlenden Report nach Werkzeugabbruch als error. Für R liefert orchestrator/lib/r-mutation.R den Bericht des CRAN-Pakets muttest unverändert in diesem Schema.

Für R-Pakete liefert das Template die Kommandos selbst: orchestrator/lib/r-deps.R (DEPS_CMD), orchestrator/lib/r-tests.R (TEST_CMD), orchestrator/lib/r-check.sh (LINT_CMD, R CMD check --as-cran --no-manual außerhalb des Repos, ERROR oder WARNING ist fail) und orchestrator/lib/r-mutation.R (MUT_CMD). Sie liegen im Betreiber-Territorium; Konfiguration und Grenzen stehen im Preset r-paket.

orchestrator/gates.d/87-golden-adr.sh.example: verlangt bei Änderungen unter dem konfigurierten Golden-Regex oder reference/anchors/ mindestens eine geänderte Datei mit Präfix docs/decisions/ADR- im Diff seit BASE_SHA.
orchestrator/gates.d/90-laengenkorridor.sh.example: zählt Wörter gegen die Bänder der mit TEXT_LENGTH_ANCHOR benannten JSON-Datei.
orchestrator/gates.d/92-kontinuitaet.sh.example: erwartet von CONTINUITY_CMD ein JSON-Objekt mit verdict: "PASS"|"FAIL"; reason ist optional. Ein nicht erfolgreicher Judge-Prozess ist error.

Die zusätzliche Regel „jedes Gate trägt ein Kriterium, jedes Kriterium hat ein Gate oder einen Test“ steht in projektierung/SPEC-KONTRAKT.md. Der mitgelieferte Trace-Fallback erzwingt nur den oben beschriebenen Teil davon; die Gate-zu-Kriterium-Richtung muss die Projektkonfiguration anderweitig belegen.

8. Sicherheit und ihre Grenzen

Projekt-Secrets: bootstrap.sh erzeugt den ungetrackten Laufzeitpfad orchestrator/secrets.env mit Modus 600. Es verschiebt die bekannten Namen TUNNEL_TOKEN, OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, QA_API_KEY sowie Namen aus HARNESS_SECRET_KEYS aus orchestrator/config.env dorthin. Beliebige anders benannte Geheimnisse erkennt es nicht automatisch.
Rollenprozess-Umgebung: Modellprozesse starten mit env -i. Der Orchestrator übergibt ausdrücklich nur PROMPT_FILE, PATH, HOME, LANG sowie die jeweilige Rollen-Allowlist; die gestartete Shell ergänzt übliche eigene Variablen wie PWD, SHLVL und _. Secrets werden nicht automatisch in diese Prozessumgebung exportiert.
Dateisystemgrenze: Modus 600 schützt nur gegen andere OS-Benutzer. Da die Rollen-CLI unter demselben Benutzer im Checkout läuft, verhindert das Harness selbst keinen Lesezugriff auf orchestrator/secrets.env, wenn der konfigurierte CLI-Sandboxmodus ihn erlaubt. Die Umgebungsisolation ist daher keine vollständige Secret-Isolation vom Modell.
MCP-Connector: lies, liste und befehl blockieren .env- und .git-Pfade und prüfen Pfadtokens per realpath gegen die Repo-Grenze; die Tests decken auch Symlink-Fluchten ab. lessons_schreiben darf als einzige Ausnahme orchestrator/LESSONS.md ersetzen und versucht standardmäßig, nur diese Datei zu committen. Der Connector ist damit nicht vollständig read-only.
Tunnel: Quick und Named Tunnel sind implementiert. Der Tunnel ist laut orchestrator/mcp/README.md keine Authentisierung; Connector-URL und ein zufälliger Named-Tunnel-Pfad müssen wie Secrets behandelt werden.
Territorium: Die Prüfung umfasst ignorierte Pfade und schützt frühere Logs per Hash-Manifest. Pfade aus orchestrator/artifact-paths.allowlist bleiben eine ausdrückliche Ausnahme. Weil auch ignorierte Dateien vor und nach jedem Modellaufruf gehasht und kopiert werden, verlängert jede Datei im Checkout jeden Aufruf; große Quellen und Rohdaten gehören nicht in den Checkout (Preset r-paket, Abschnitt Quellen).
Shell-Freigabe nur für Rscript: Die Beispielkonfiguration erlaubt QA und Reviewer als einziges Shell-Kommando Rscript. Das ist keine Sicherheitsgrenze: Über system() startet R jedes Kommando. Schutz bleiben die Territoriumsprüfung und der Rollback des Orchestrators.
Was der Wächter nicht sieht: Er prüft die Rollenkommandos, nicht die Einstellungsdateien der CLIs unter HOME. Eine Freigabe dort wirkt wie ein Bypass, ohne im Kommando zu erscheinen: etwa toolPermission: always-proceed der Antigravity CLI, tools.allowed in ~/.gemini/settings.json, permissions.allow in ~/.qwen/settings.json oder in ~/.claude/settings.json. Diese Dateien zu prüfen ist Betreiberpflicht (RUNBOOK).
Provenienz: orchestrator/state/<MS>/gates.json enthält Basis- und aktuellen SHA sowie Werkzeugversionen. orchestrator/logs/orchestrate.log protokolliert ausgewählte effektive Ablaufwerte, aber nicht die vollständige Konfiguration.

9. Beobachtung und Betrieb

STATUS.md und orchestrator/state/summary.json zeigen denselben aus dem Zustand gerenderten Fortschritt; summary.json trägt "contract": 1 und ts als Heartbeat.
orchestrator/logs/orchestrate.log ist die Metaspur. Modelltranskripte und Promptarchive folgen den in Abschnitt 3 genannten unterschiedlichen Namensmustern.
orchestrator/notify.sh sendet best-effort. Der Orchestrator ruft es für FATAL, PARKED, ARBITER, NEEDS_HUMAN und DONE auf; orchestrator/watchdog.sh nutzt es für STALE.
bootstrap.sh installiert keinen Watchdog-Cronjob. Das Beispiel in RUNBOOK.md startet orchestrator/watchdog.sh alle 15 Minuten; der Default WATCHDOG_STALE_SECONDS=1800 meldet erst nach mehr als 30 Minuten Heartbeat-Alter und nur bei lebender Lock-PID.
Ein abgewiesener Doppelstart verändert weder Heartbeat noch Benachrichtigungen des laufenden Orchestrators.
Wiederaufnahme erfolgt durch erneuten Start; vorhandene Phasenmarker werden berücksichtigt. STOP und PARKED müssen wie in RUNBOOK.md beschrieben gezielt aufgelöst werden.
Bei PUSH_REMOTE=1 und vorhandenem Remote origin versucht der Orchestrator nach jedem DONE ein git push --follow-tags; ein Fehlschlag wird nur als Warnung geloggt.

10. Selbsttest des Templates

bash tests/template/run-all.sh materialisiert temporäre Git-Repositories unter /tmp und fährt die echte Orchestrator-/Gate-/Statuslogik mit tests/template/fake-model.sh statt echten Modell-CLIs.

Test	Tatsächlich geprüfter Schwerpunkt
T-1	Bootstrap zweimal, Statusvertrag, externe MCP-Umgebung, bekannte Secret-Migration; der öffentliche Tunnel bleibt dabei deaktiviert
T-2	zwei Meilensteine, rote Gates, Rework, Transport- und Territoriums-Retry, Commits und Tags
T-3	Rebuild ab Runde 4, Arbiter `HUMAN` mit derselben Effort-Stufe wie der Reviewer, PARKED mit Fortsetzungshinweis `git rm` und Exit 3
T-4	Notify, Watchdog, Doppelstart, fremdbefüllter Lock und Statuspräzedenz
MCP-Allowlist	aktuell 72 positive, negative, Struktur-, grep- und Symlink-Fälle
T-5B / T-5	sechs ausgeführte Verhaltensnachweise und Vollinventar gegen `docs/template/T5-SOLL.md`
T-6	aktive QA, QA-Park, protokollierte strikte QA-Routenprobe (FATAL bei stiller Modus-Rückstufung), acht Fortschritte mit Autonomiestufe 0 und ziffernlose IDs
T-7	Territorien, Logschutz, Rollen-Umgebung, Flag-/Guard-Prüfung mit allen Mustern der Verbotslisten (Negativfälle) und `auto_edit`/`auto-edit` samt Routenprobe (Positivfälle), veraltetes und fehlendes Verdict als FATAL samt Wiederanlauf, Vertrags- und Manifestfehler
T-8	Gate-error/fail, Mutation-Ratchet, Trace, Golden-ADR und Territory-Marker
T-9	`tools/install-into.sh`: Projektdateien unberührt, Zusammenführen von `.gitignore`, `.gitattributes` und `.Rbuildignore`, `reference/quellen/` ignoriert, Katalog, docs/pkgdown-Konfliktbericht, Probelauf, Wiederholung, Modi 100755 bei `core.filemode=false` und im frischen Klon
T-10	Preset `r-paket`: Einsetzen per Installer, die markierten Preset-Blöcke unverändert, M0 mit Attrappen bis DONE, deps/lint/tests/trace/territory/mutgate/golden-adr grün, `R/` unverändert, danach echter muttest-Lauf gegen `86-mutgate`; ohne R „übersprungen: R fehlt“, nie PASS

Der Suite-Lauf hängt Auditzeilen an den ignorierten Laufzeitpfad orchestrator/mcp/calls.log an. Das ist erwarteter Testzustand, kein versioniertes Artefakt.

Voraussetzungen sind bash, git, jq, tmux, curl, timeout und python3 mit venv. T-1 legt dabei eine temporäre Umgebung an und installiert mcp==1.28.1 aus PyPI; mit HARNESS_MCP_PYTHON lässt sich stattdessen ein vorhandenes Python mit diesem Paket verwenden. T-10 braucht R mit testthat und pkgload, für den Mutationsteil muttest; fehlt R, endet T-10 mit Exit 77, und die Schlusszeile nennt T-10 als übersprungen. Die temporären Repos übernehmen die Dateimodi aus dem Git-Index, nicht aus dem Arbeitsbaum, damit sie einem frischen Klon entsprechen; auf /mnt/c sind sonst fast alle Dateien lokal ausführbar. Unter Windows laufen die Selbsttests in WSL, etwa wsl bash -lc "cd /mnt/c/<Pfad>/harness-template && tests/template/run-all.sh"; .gitattributes sorgt dafür, dass auch ein Windows-Klon LF-Zeilenenden hat.

Gefälschte Schlüssel. Alle Schlüssel, Tokens und Passwörter in den Tests (tests/template/, orchestrator/mcp/tests/) und in den Abnahmeberichten unter docs/template/abnahme/ sind absichtlich gefälscht, etwa sk-fixture-MUST-NOT-LEAK, sk-or-v1-DEADBEEFsecret123 oder GEHEIM-TUNNEL-TOKEN-123. An ihnen prüfen die Tests, dass Geheimnisse nicht in die Umgebung der Modellrollen gelangen, aus orchestrator/config.env nach orchestrator/secrets.env verschoben werden und über den MCP-Connector nicht lesbar sind; die Abnahmeberichte zeigen mit ihnen, wo frühere Fassungen durchlässig waren.

11. Herkunft und Abnahme-Archiv

Laut docs/template/BAUPLAN.md wurde die Vorlage aus dem Projekt Demiurg extrahiert, einem eigenen Computerspiel-Projekt des Autors (daher Meilensteinnamen wie „Waffe 1: Meteorit“ im Beispiel unter projektierung/beispiel/). Mit der Vorgängerfassung dieser Entwicklungsumgebung entstand von Ende Juni bis Mitte Juli 2026 die Liquiditätsanwendung, veröffentlicht als liquiditaetsplanung. Die Vorlage ist die verallgemeinerte Nachfolgerin beider Einsätze.

Die beiden ursprünglichen adversariellen Berichte unter docs/template/abnahme/ endeten mit FAIL, nicht mit Abnahme. Darauf folgten der achtteilige Rework R1–R8, eine unabhängige Wiederabnahme mit Rot-Proben gegen den Vor-Rework-Stand, zwei neue Nachbefunde zur MCP- Symlinkgrenze und zur Watchdog-Uhr sowie deren Nacharbeit/Nachprüfung. Die Berichte und Betreiberentscheide E1–E9 bleiben vollständig im Archiv.

Der annotierte Git-Tag v1.0 existiert und markiert den abgeschlossenen Template-/Nachprüfungsstand vor dieser späteren README-Korrektur.

Versionen. v1.0 ist der Abnahmestand vom 6. August 2026. v1.0.1 ist die veröffentlichte Fassung mit Lizenz und Zitierdaten: Orchestrator, Gates, Prompts und Tests sind gegenüber v1.0 unverändert. Hinzu kommen LICENSE, CITATION.cff, .zenodo.json und .gitattributes, die README-Ergänzungen seit v1.0, ein Eintrag .claude/ in .gitignore, ein an den Code angeglichener Satz in projektierung/SPEC-KONTRAKT.md §6 und ein Halbsatz zur Herkunft in projektierung/beispiel/README.md. In den Abnahmeberichten sind lokale Pfade und Benutzernamen für die Veröffentlichung neutralisiert (etwa ~/dev/… statt des Home-Verzeichnisses); sonst sind sie unverändert.

v1.1.0 (23. Oktober 2026) ist der Umbau für R-Pakete und drei Modellanbieter. Er ändert am Orchestrator zwei Stellen: die Verbotslisten der Rollenkommandos (zusätzlich --approval-mode yolo, dangerously-bypass, Klassifikator-Freigaben und Resume-Unterkommandos) und das Protokoll der QA-Routenprobe. Neu sind das Preset r-paket mit den R-Gate-Kommandos unter orchestrator/lib/, der muttest-Adapter, die Gemini-Policy für QA, tools/install-into.sh, der Beispielblock in config.env.example, die Selbsttests T-9 und T-10 sowie Ergänzungen in T-3, T-6 und T-7. Die temporären Test-Repos übernehmen die Dateimodi jetzt aus dem Git-Index. Keine bestehende Prüfung und keine Schwelle wurde abgeschwächt; Ausführung und Messwerte stehen in PROGRESS.md.

v1.1.1 (23. Oktober 2026) schließt eine Lücke in verdict(): Das Verdict muss aus der laufenden Runde stammen. Bis 1.1.0 las der Orchestrator ein liegengebliebenes Verdict einer früheren Runde, wenn eine Review-Phase kein neues schrieb; ein altes PASS konnte so einen Meilenstein über ungeprüftem Rework-Code abschließen. Ein fehlendes oder älteres Verdict ist jetzt FATAL, und die Meldung erscheint auf der Konsole. Die Fortsetzungshinweise für versionierte Phasen- und Parkmarker nennen git rm und einen Commit. Prompts 30 und 50, SCHEMA.md und contracts/PROTOCOLS.md verlangen "round": <laufende Runde>. Belege in PROGRESS.md.

12. FAQ

Andere Modelle einsetzen? Ändere das jeweilige Rollenkommando in orchestrator/config.env. Die Felder BUILDER_MODEL, REVIEWER_MODEL und QA_ENDPOINT wählen selbst kein Modell und keinen Endpoint aus.

Geht es ohne QA? Ja. Bei leerem QA_CMD ist QA standardmäßig aus. Ist zugleich QA_REQUIRED_FROM auf eine Manifest-ID gesetzt, parkt das Harness ab dieser Position, solange QA_ENABLED nicht 1 ist.

Kann ich das Template über ein bestehendes Repo legen? Ja, mit tools/install-into.sh <zielrepo> (Abschnitt 5). Es überschreibt keine Projektdateien, führt .gitignore, .gitattributes und bei R-Paketen .Rbuildignore zusammen und meldet Konflikte, statt sie aufzulösen. Der andere Weg bleibt ein frischer Klon mit Originalmaterial unter reference/ und einer projektspezifisch geplanten Portierung.

Muss ich docs/template/ behalten? Nein. Es ist nur das interne Bau- und Abnahme-Archiv des Templates und kann im Zielprojekt entfernt werden.

Wo greife ich als Betreiber ein? Bei Intake, Freigabe, Gate-Auswahl, orchestrator/config.env, orchestrator/secrets.env, toolchain.json, Betriebsereignissen nach RUNBOOK.md und den konkreten Fragen in orchestrator/ESCALATION-<MS>.md.

13. Designphilosophie

Das Harness verbindet etablierte Software- und Betriebspraxis mit Forschungslinien zu Multi-Agent-Systemen, Verifikation und Kontextsteuerung. Die Verweise unten ordnen die Ideen fachlich ein; sie belegen nicht, dass jede Funktion aus genau dieser Publikation abgeleitet wurde. Die Tabelle ist keine systematische Forschungsbibliografie, und das Repository enthält keinen Vergleichsversuch, der eine Überlegenheit gegenüber einem einzelnen Agenten oder das „bestmögliche“ Ergebnis beweist.

Die letzte Spalte trennt deshalb vier Ebenen: hart bedeutet durch Orchestrator, Schema, Territoriumsprüfung oder Test erzwungen; konfigurationsabhängig gilt nur bei aktivierter Vorlage oder Projektkonfiguration; Vertrag/Prompt ist eine Rollenregel, aber kein vollständiger technischer Beweis; Designziel wird unterstützt, jedoch nicht geprüft.

Gewaltenteilung und Dekorrelation

Feature	Praxis- oder Forschungslinie	Wofür es gut ist	Tatsächliche Umsetzung und Grenze
Builder und Abnehmer sind getrennt	Vier-Augen-Prinzip, spezialisierte Rollen wie in MetaGPT und ChatDev, dazu der Befund zur Selbstbevorzugung von LLM-Judges	Verhindert, dass der Autor Produktcode und Abnahmekriterien passend zueinander ändert oder die eigene Arbeit zertifiziert	Hart für Rollen und Schreibterritorien: Aktive Rollen laufen als getrennte Prozesse; Builder schreibt keine Abnahmetests, Reviewer keinen Produktcode. Die Konfiguration kann trotzdem dasselbe Modell oder sogar dasselbe Rollenkommando verwenden; personelle oder modellseitige Unabhängigkeit wird nicht nachgewiesen.
QA als dritte, adversarielle Rolle	Red Teaming und Ensemble-Idee; unterschiedliche Fehlerquellen sollen blinde Flecken reduzieren, obwohl LLM-Fehler laut Korrelationsbefunden nicht automatisch unabhängig sind	Sucht ausführbare Gegenbeispiele statt einer weiteren bestätigenden Bewertung und besitzt bewusst keine Verdict-Macht	Konfigurationsabhängig: QA erzeugt E2E-/Fuzz-Nachweise und kein Urteil. Sie ist standardmäßig optional. Drei Rollen sind nicht automatisch drei Modellfamilien; Familienidentität und Fehlerdekorrelation prüft das Harness nicht. `BUILDER_MODEL`, `REVIEWER_MODEL` und `QA_ENDPOINT` wählen selbst kein Modell.
Frischer Arbiter mit bindender Ablaufwirkung	„Fresh eyes“, Begrenzung von Verankerung und Multi-Agent-Debatten mit operationaler Abbruchregel	Beendet festgefahrene Rework-Schleifen und überführt den Fall eindeutig in Zusatzrunden oder einen Human-Park	Hart im Ablauf: Der Arbiter startet als neuer Prozess und sein strukturiertes Ergebnis steuert den weiteren Zustand. Er kann jedoch über dasselbe `REVIEWER_CMD` und damit dieselbe Modellfamilie laufen; kognitive Unabhängigkeit ist ein Designziel, kein geprüfter Fakt.

Deterministische Verifikation und Anti-Halluzinations-Grounding

Feature	Praxis- oder Forschungslinie	Wofür es gut ist	Tatsächliche Umsetzung und Grenze
Modelle dürfen Gates nur lesen	Externe Verifikation statt bloßer Selbstkritik; Forschung zeigt klare Grenzen rein intrinsischer Selbstkorrektur. Die Trennung begrenzt außerdem das in einem Coding-Audit zu Reward Hacking untersuchte Manipulieren von Tests.	Nur der Betreiber definiert die Wahrheitsprüfung; ein Modell kann ein rotes Gate nicht durch Umschreiben von `gates.json` oder der Gate-Auswahl grün machen	Hart für Schreibrechte: Modellrollen dürfen Orchestrator-Zustand und aktive Gates nicht schreiben; `orchestrator/verifier.sh` erzeugt die Fakten. Deterministisch ist die Kontrolllogik, nicht zwingend jeder konfigurierte Gate-Befehl oder externe Dienst.
Abnahmetests entstehen vor der Implementierung	Test-first/TDD und ausführbare Spezifikation; empirische Einordnung etwa in der Test-first-Studie	Fixiert den Vertrag, bevor der Builder ihn erfüllen kann, und verhindert nachträglich maßgeschneiderte Abnahmetests	Hart für Reihenfolge und Eigentum: Der Reviewer schreibt die Acceptance-Verträge vor BUILD, ein roter Ausgang ist erlaubt und erwartet. Die ACCEPTANCE-Phase allein beweist jedoch nicht, dass jeder neue Test tatsächlich rot ausgeführt wurde; dieser Beleg muss aus den konfigurierten Gates kommen.
`error` ist nicht `fail`	SRE-Trennung zwischen Infrastrukturstörung und fachlichem Fehler	Transport- oder Umgebungsfehler verbrauchen keine fachlichen Rework-Runden	Hart: Ein reiner Gate-`error` wird standardmäßig nach dem ersten Versuch zweimal wiederholt und anschließend als Infrastrukturfall geparkt; ein gemischtes Ergebnis mit `fail` bleibt ein fachlicher Fehlschlag.
Mutation-Ratchet	Mutation Testing seit DeMillo, Lipton und Sayward plus Ratchet-Prinzip; relevant ist auch der Befund, dass Benchmark-Tests inkorrekte SWE-bench-Patches akzeptieren können	Prüft, ob Tests Fehler wirklich entdecken, und verhindert ein stilles Absinken des erreichten Mutation Scores	Konfigurationsabhängig: `orchestrator/gates.d/86-mutgate.sh.example` liest einen Stryker-Bericht, erzwingt Floor und bisherigen Bestwert und kennt genehmigte äquivalente Mutanten. Ohne aktiviertes Gate und erzeugten Bericht gibt es keine Mutation-Prüfung.
Differential-, Property-, metamorphe und Invariantentests	Differential Testing, Metamorphic Testing und Property-Based Testing wie QuickCheck	Prüft gegen ein ausführbares Original oder gegen allgemeine Relationen, wenn kein einzelner Sollwert als Orakel existiert	Vertrag/Prompt: Die Rollenregeln verlangen geeignete Orakel, feste Seeds und Erhaltungsaussagen. Das Template liefert dafür keine universelle Testmaschine; Fixtures, Toleranzen, Relationen und Referenzaufrufe müssen im projektierten Repo real implementiert werden.
Anker, Quellenzitat und Golden-ADR	Datenprovenienz und kontrollierte Golden-Master-Änderungen	Verhindert empirische Konstanten aus Modellgedächtnis und macht Änderungen an erwarteten Ergebnissen begründungspflichtig	Hart als Rollenvertrag, Gate konfigurationsabhängig: Empirische Werte gehören nach `reference/anchors/*.json` und brauchen Quelle, Beleg-Zitat, Einheit und Toleranz. `orchestrator/gates.d/87-golden-adr.sh.example` erzwingt bei Golden-Änderungen ein ADR nur, wenn das Gate aktiviert ist.
Traceability-Check	Requirements Traceability aus qualitäts- und sicherheitskritischer Entwicklung	Verbindet Spezifikationskriterien mit ausführbaren Abnahmen und erschwert erfundene oder ungedeckte Anforderungen	Konfigurationsabhängig und bewusst leichtgewichtig: `orchestrator/gates.d/70-trace.sh.example` prüft Manifest, Kriterien, exakte Zitate/Quelldateien und deren Vorkommen in Acceptance-Dateien. Es beweist keine vollständige Gate-zu-Kriterium-Matrix und verlangt nicht in jeder einzelnen Testdatei eine Kriterien-ID.
Unabhängige Mini-Referenz für kritische Logik	N-Version Programming	Gibt dem Reviewer einen zweiten Rechenweg statt nur einer Plausibilitätsprüfung des Produktcodes	Vertrag/Prompt: Der Reviewer soll kritische Logik unabhängig nachrechnen. Weder die algorithmische Unabhängigkeit noch eine Übereinstimmung zweier Modellfamilien wird maschinell geprüft.
Compiler, Toolchain und eingefrorene Manifeste	Reproduzierbare Builds, Typechecking und Dependency-Locking	Lässt erfundene APIs, unauflösbare Versionen und nicht reproduzierbare Abhängigkeiten an ausführbaren Werkzeugen scheitern	Hart für den Toolchain-Vertrag, sonst konfigurationsabhängig: `bootstrap.sh` erzeugt `toolchain.json` aus `toolchain.json.example`; Schema, deklarierte Laufzeiten und Manifestexistenz werden geprüft. Dependency-, Lint-, Test- und Repro-Gates sind Projektvorlagen. Das Template stellt keine vollständig hermetische Container- oder Build-Umgebung her.
Screenshot-Gate	Visuelle Regression und multimodale Abnahme	Macht UI-Behauptungen prinzipiell an Bildartefakten prüfbar	Konfigurationsabhängig mit enger Grenze: `orchestrator/gates.d/84-shots.sh.example` führt `SHOTS_CMD` aus und bereitet das Artefaktverzeichnis vor. Das generische Gate beweist weder, dass Bilder erzeugt wurden, noch dass ein multimodales Modell sie tatsächlich angesehen hat; das muss das Projektkommando und der Reviewprozess sicherstellen.

Kontext-Engineering und spec-getriebene Steuerung

Feature	Praxis- oder Forschungslinie	Wofür es gut ist	Tatsächliche Umsetzung und Grenze
Jede Phase ist eine frische Einweg-Session; das Repo ist Gedächtnis	Stateless Workflows und Befunde zur schlechteren Nutzung langer Kontexte, etwa Lost in the Middle	Reduziert Kontextdrift, macht Übergaben nachvollziehbar und erlaubt Wiederaufnahme aus versioniertem Zustand	Hart auf Prozessebene: Resume-/Continue-Flags sind verboten und jede Modellphase startet neu. Das garantiert weder identische Modellausgaben noch, dass ein externer Provider keinerlei serverseitigen Zustand hält.
Kontextliste je Prompt und Review-Diff seit `plan/<MS>`	Context Engineering und Changeset-orientiertes Review	Begrenzt die primäre Lesemenge auf Auftrag, Regeln, Fakten und die Änderung des aktuellen Meilensteins	Hart für die erzeugten Prompts, nicht als Lese-ACL: Die Prompts nennen Pflichtdateien; Review- und QA-Prompts zusätzlich den Diff-Bezug. Das Modell kann technisch weitere erlaubte Repo-Dateien lesen; vollständige Aufmerksamkeit für die Liste wird nicht bewiesen.
Dateibasierte Handoffs, Schemata und stabile Einwand-IDs	Strukturierte Übergaben, endliche Verhandlung und ADRs im Stil von Nygard	Macht Läufe prüfbar, wiederaufnehmbar und Konflikte punktweise beantwortbar	Gemischt: Verdicts, Pflichtfelder, Rundenbudgets und Zustandsübergänge sind hart; Begründungsqualität, korrekte Spec-Zitate und inhaltlich unabhängige Prüfung bleiben Vertrag/Prompt.
Kuratierte `LESSONS.md` mit Größenlimit	Reflexions- und Agent-Memory-Praxis mit bewusster Destillation	Bewahrt wiederverwendbares Wissen, ohne unbegrenzt selbst erzeugte Memos und Fehler anzusammeln	Hart für den MCP-Schreibpfad: `lessons_schreiben` ersetzt gezielt `orchestrator/LESSONS.md` und begrenzt sie auf 16.000 Zeichen. Auswahl und Wahrheit der Lektionen werden kuratiert, nicht automatisch bewiesen.
Projektierung, Intake und `projektierung/SPEC-KONTRAKT.md`	Spec-driven Development, wie es auch Spec Kit und Kiro Specs verfolgen	Führt vor dem autonomen Lauf zu einer klaren Vision, überprüfbaren Kriterien und einem messbaren Qualitätsmaßstab	Betreiberprozess: Checklisten, Vorlagen und Freigabeschritte existieren, werden aber nicht vom normalen Meilensteinlauf automatisch inhaltlich ausgefüllt. Die Qualität des Maßstabs bleibt eine Betreiberentscheidung.
Entschieden, offen, verworfen und `BACKLOG.md`	Scope- und Decision-Management	Verhindert, dass Brainstorming still zur Anforderung wird oder nicht gelöste Befunde verschwinden	Vertrag/Prompt: Die Taxonomie und Backlog-Pflichten sind vorgegeben; Vollständigkeit und korrekte Einordnung lassen sich nicht allgemein maschinell beweisen.

Zuverlässigkeitstechnik, Provenienz und Sicherheit

Feature	Praxis- oder Forschungslinie	Wofür es gut ist	Tatsächliche Umsetzung und Grenze
Retry mit Backoff nach Fehlerklasse	Resilienzpraxis verteilter Systeme	Fängt erkannte Rate-Limits, Netzwerk-Timeout-Muster und vorübergehende Transportfehler ab, ohne eine fachliche Rework-Runde zu zählen	Hart für erkannte Muster: Retries und Backoff sind begrenzt. Die Erkennung ist regex-basiert, hat keinen Jitter und kann unbekannte Providertexte oder ein bloß anders formuliertes `HTTP 429` übersehen. Ein durch `PHASE_TIMEOUT` ausgelöster Exit 124 wird nur dann wiederholt, wenn der Logtext zusätzlich einem Transportmuster entspricht.
Atomarer Lock, verwaiste Locks, Heartbeat, Watchdog, STOP, Timeouts und Wiederaufnahme	SRE- und Distributed-Systems-Praxis	Verhindert Doppelstarts, unterscheidet abgestürzte von aktiven Läufen und setzt harte Grenzen gegen Endlosschleifen	Hart mit Betriebsgrenzen: Lock, PID-Prüfung, Marker und Rundenbudgets sind implementiert; der Watchdog muss extern geplant werden. Der Heartbeat wird an Phasengrenzen aktualisiert, daher kann eine lange Modellphase vorübergehend alt aussehen. STOP beendet als FATAL; fehlt das Systemprogramm `timeout`, läuft der Fallback ohne erzwungenes Modell-Timeout.
Leiter Rework → Rebuild → Arbiter → Park	Begrenzte Eskalationspolitik gegen lokale Reparaturschleifen	Wechselt nach wiederholtem Scheitern vom Patchen zum Neuaufbau, terminiert Streit und lässt unabhängige Meilensteine weiterlaufen	Hart, sofern die Stufen aktiviert sind: Rebuild beginnt ab der konfigurierten Runde und setzt nur `REBUILD_PATHS`, nicht automatisch das gesamte Builder-Territorium, auf den Planstand zurück. Geparkte Abhängigkeiten blockieren weiterhin ihre Nachfolger.
SHA-, Werkzeug-, Konfigurations-, Log- und Tag-Provenienz	Reproduzierbarkeitskultur und Provenienzmodelle wie SLSA	Macht sichtbar, welcher Stand mit welchen Werkzeugen geprüft und abgeschlossen wurde	Hart, aber nicht vollständig: `gates.json` enthält Basis-/aktuellen SHA und Werkzeugversionen; Logs, Phasencommits und Tags dokumentieren den Lauf. Die `CONFIG`-Zeile enthält ausgewählte Ablaufwerte, nicht jede Konfiguration, jeden Dokument-Hash oder eine hermetische Attestation.
Least Privilege gegenüber den Modellrollen	Separation of Duties und Least Privilege, etwa die Kontrollen AC-5/AC-6 in NIST SP 800-53	Begrenzt Schäden durch Prompt Injection, Fehlbedienung oder absichtliches Umgehen der Abnahme	Hart innerhalb der Harness-Kontrollen: Git-Diff-Territorien einschließlich ignorierter Pfade, Log-Hash-Schutz, minimierte Rollen-Umgebungen, bekannte Secret-Migration und verbotene Bypass-Flags sind implementiert. Das ist keine OS-Benutzer- oder vollständige Leseisolation; Rollen teilen Repo und `HOME`, externe CLI-Sandboxes müssen separat wirksam sein, und Betreiber können die CLI-Rollenwächter bewusst abschalten.
Gehärteter MCP-Pfadzugriff	Path-Traversal-Abwehr mit kanonischen Pfaden, Symlink-Prüfung und Denylist für sensible Dateien	Verhindert, dass relative Pfade oder Symlinks aus der Repository-Grenze beziehungsweise in `.env`- und `.git`-Inhalte führen	Hart für die getesteten Connector-Werkzeuge: `realpath`-, Repo-, `.env`-, `.git`- und Symlink-Prüfungen sind abgedeckt. Der Connector ist wegen `lessons_schreiben` nicht vollständig read-only; ein veröffentlichter Tunnel bringt laut eigener Dokumentation keine Authentisierung mit.

Der größte belastbare Nutzen entsteht damit nicht aus der bloßen Zahl der Modelle, sondern aus getrennten Schreibrechten, ausführbaren Abnahmekriterien, begrenzten Schleifen und prüfbarer Provenienz. Eine vollständige, feingranulare Funktionsinventur des v1.0-Templates steht in docs/template/T5-INVENTAR.md; die Tabellen hier beschreiben die übergeordneten Entwurfsentscheidungen und deren Grenzen.

14. Erkenntnisse aus dem Einsatz

Im Einsatz meldete ein Prüfmodell Arbeitspakete als erledigt, obwohl vorgeschriebene Prüfläufe fehlten. Seitdem genügt ein Modellurteil allein nie; abgeschlossen ist ein Paket erst nach bestandenen ausführbaren Prüfungen. In der Vorlage ist das so umgesetzt:

orchestrator/orchestrate.sh, Funktion run_ms: Ein Meilenstein endet nur, wenn das Reviewer-Verdict PASS lautet und der Gate-Lauf pass ergibt ([ "$verdict_value" = PASS ] && [ "$gate_rc" = 0 ]). Sonst folgen die nächste Runde, der Schiedsrichter oder der Park.
orchestrator/verifier.sh: Die Gate-Skripte führt der Orchestrator selbst aus und schreibt das Ergebnis nach orchestrator/state/<MS>/gates.json. Ohne aktives Gate lautet das Ergebnis error, nicht pass.
path_allowed und ownership_check in orchestrator/orchestrate.sh: Keine Modellrolle darf orchestrator/state/** und damit die Gate-Ergebnisse schreiben.
AGENTS.md, Integritätsregel 4: „Kriterium erfüllt“ heißt, der Befehl wurde ausgeführt und sein echter Output steht im Handoff oder in PROGRESS.md.
Selbsttest T-8, Szenario TERROR: Die Reviewer-Attrappe meldet PASS, ein Gate meldet error. Der Meilenstein wird nicht abgeschlossen, sondern nach zwei Wiederholungen geparkt (Exit 3).

15. Entstehung

Die Vorlage ist mit agentengestützter Codeerzeugung entstanden. Commits des Agenten sind als solche gekennzeichnet: 19 der 20 Commits bis 7a27de2 tragen den Autor Codex <codex@local>; der übrige (3d95ed7) legt den Bericht der unabhängigen Wiederabnahme ab. Die Veröffentlichungsfassung 1.0.1 hat Claude Code vorbereitet; die Commits dazu nennen das im Vermerk Co-Authored-By. Den Umbau zu 1.1.0 hat Claude Code mit Claude Opus 5.5 nach dem Umbau-Auftrag des Betreibers ausgeführt, ebenso die Korrektur 1.1.1; auch diese Commits tragen den Vermerk.

Eigenanteil von Daniel Andreas Moj: Architektur, Rollen-, Rechte- und Eskalationsregeln, Prüfstrategie sowie Prüfung und Freigabe der Ergebnisse. Bauplan, Rework-Auftrag und Betreiberentscheide E1–E9 unter docs/template/ dokumentieren diese Vorgaben.

16. Zitieren

Bitte über die Angaben in CITATION.cff zitieren; GitHub zeigt sie unter „Cite this repository“ an. Die Fassung 1.0.1 ist bei Zenodo archiviert; eine eigene DOI für 1.1.0 und 1.1.1 vergibt Zenodo erst mit deren Archivierung, bis dahin führt die Konzept-DOI zur neuesten archivierten Fassung:

Version 1.0.1: 10.5281/zenodo.23352918
alle Versionen (Konzept-DOI, führt stets zur neuesten Version): 10.5281/zenodo.23352917

Moj, Daniel Andreas (2026): harness-template: Vorlage für eine Multi-Agenten-Entwicklungsumgebung mit ausführbaren Abnahmeprüfungen. Software, Version 1.1.1. Zenodo. https://doi.org/10.5281/zenodo.23352917.

Name		Name	Last commit message	Last commit date
contracts		contracts
docs		docs
orchestrator		orchestrator
projektierung		projektierung
reference/anchors		reference/anchors
tests/template		tests/template
tools		tools
.gitattributes		.gitattributes
.gitignore		.gitignore
.zenodo.json		.zenodo.json
AGENTS.md		AGENTS.md
BACKLOG.md		BACKLOG.md
CITATION.cff		CITATION.cff
CLAUDE.md		CLAUDE.md
IMPLEMENTATION-RULES.md		IMPLEMENTATION-RULES.md
LICENSE		LICENSE
PROGRESS.md		PROGRESS.md
README.md		README.md
RUNBOOK.md		RUNBOOK.md
STATUS.md		STATUS.md
bootstrap.sh		bootstrap.sh
config.env.example		config.env.example
start.sh		start.sh
toolchain.json.example		toolchain.json.example

Latest commit

History

Folders and files

Repository files navigation