Add bounded gap/reuse preflight with live open-work discovery

docs/EXTERNAL_PATTERN_SCOUT.de.md

@@ -23,6 +23,104 @@ Ein begrenzter Scout ist sinnvoll, wenn mindestens eines davon gilt:
 
 Normale Produktarbeit darf nicht blockieren, nur weil kein aktueller Scout existiert.
 
+## Suchbreite
+
+Gesucht wird nach dem **Problem**, nicht nur nach Projekten, die wie Loop42 aussehen.
+
+Mit den wörtlichen Begriffen aus Nutzerziel oder Projekt starten und dann bewusst
+auf Synonyme, Mechaniken und benachbarte Fachgebiete erweitern. Ein brauchbarer
+Kandidat muss sich nicht selbst als KI-Agent, Loop oder Orchestrator bezeichnen,
+wenn er denselben Fehlermodus löst.
+
+Sinnvolle Suchfamilien sind unter anderem:
+
+- KI / Agenten / Prompts / Context Engineering / Memory / Evals / Grader;
+- Durable Workflows / State Machines / Checkpoints / Replay / Reconciliation;
+- Distributed Systems / Idempotency / Optimistic Concurrency / Leases / Fencing /
+  Event Sourcing / Saga / Outbox;
+- Queues / Worker / Supervision / Retry / Circuit Breaker / Dead-Letter Handling /
+  Backpressure / begrenzte Parallelität;
+- inkrementelle Buildsysteme / Dependency Graphs / Invalidierung /
+  content-addressed State / Reproduzierbarkeit / Caching;
+- Policy / Provenance / Attestations / Audit / Autorisierung;
+- Fault Injection / Chaos Engineering / Model Checking / Property-based Testing;
+- relevante technische Regelsysteme, wenn ihr Problem zum Consumer-Fall passt.
+
+Ein Scout soll relevante Familien stichprobenartig mischen, statt nur kleine
+Varianten derselben Produktkategorie zu suchen. Keyword-Erweiterung ist eine
+Discovery-Heuristik und keine Erlaubnis, einen größeren Backlog zu erzeugen.
+
+Ein ähnliches Produkt ist weder Voraussetzung noch automatisch ein guter Fund.
+Bevorzugt wird die kleinste übertragbare Mechanik, die das aktuelle Problem löst.
+
+## Perspektiv-Probe
+
+Wenn Unsicherheit, wiederholtes Scheitern oder eine wesentliche Designentscheidung
+es rechtfertigt, DARF der Scout das Problem in einem begrenzten Durchlauf neu
+betrachten, bevor Kandidaten ausgewählt werden. Nur Linsen verwenden, die Suche
+oder Pre-Mortem tatsächlich verändern können:
+
+- **Danach-Linse** — wenn der aktuelle Plan funktioniert, was wird zum nächsten
+  Engpass, zur ungültigen Annahme oder zum Bedienaufwand?
+- **Umkehr-Linse** — welche zentrale Annahme würde den aktuellen Problemrahmen
+  falsch machen, und zeigt Entfernen oder Umkehren einer Abhängigkeit einen
+  einfacheren Weg?
+- **Außen-Linse** — wie würde ein Operator, Maintainer, Safety-Reviewer oder ein
+  benachbartes Fachgebiet dasselbe Problem beschreiben?
+
+Die Probe liefert höchstens ein oder zwei konkrete alternative Hypothesen oder
+Suchrichtungen. Sie ist keine Brainstorming-Pflicht und MUSS entfallen, wenn sie
+keine eigene Entscheidung, kein neues Evidence-Ziel und keine neue
+Fehlerhypothese erzeugt.
+
+
+## Lückenerkennung und Wiederverwendungsprüfung
+
+Vor größerer neuer Infrastruktur, einer wichtigen Workflow-Änderung oder
+wiederholtem Scheitern **eine begrenzte Lücken- und Reuse-Probe in RECONCILE /
+TARGET** durchführen. Sie ist Teil des vorhandenen Matrixloop und der
+/truth-/gaps-Prüfungen, **keine zusätzliche Loop-Stufe**, kein Agent, Scheduler,
+Zustandsspeicher, Recht oder neuer Wahrheitsanspruch.
+
+1. **Zuerst abgleichen.** Vereinbartes Ziel, Abnahmekriterien, aktuelle Quelle
+   und Revision, vorhandene Implementierung, offene Issues/PRs/Branches,
+   frühere Recherche und Fähigkeiten bereits vorhandener Werkzeuge festhalten.
+   Designziele, Drafts und Tests auf alten Revisionen sind keine integrierten
+   aktuellen Funktionen.
+2. **Kleinen Umfang abstecken.** Den betroffenen durchgängigen Arbeitsweg und
+   Fehlermodi stichprobenartig prüfen statt nur die erstgenannte Bibliothek/API.
+   Bei Bedarf Bedienweg, Sicherheit, Recovery sowie Dependency-/License-Folgen
+   einbeziehen; nicht bei jedem Aufruf das gesamte Produkt auditieren.
+3. **Suchabdeckung ehrlich kennzeichnen.** Je relevantem Ausschnitt zwischen
+   `CHECKED_NO_DELTA` (auf benannter Grundlage geprüft, kein nützlicher Gewinn),
+   `USEFUL_CANDIDATE` (belegte prüfbare Alternative), `NOT_SEARCHED`
+   (Recherche-Lücke) und `BLOCKED_UNKNOWN` (Quelle, Fähigkeit oder Beleg
+   fehlt) unterscheiden. **NOT_SEARCHED ist nicht NO_USEFUL_DELTA.** Fehlende
+   Quellen sind kein Negativbefund; Grenze nennen und abhängige Behauptung stoppen.
+4. **Wiederverwenden vor Neuerfinden.** Vorhandene eigene Implementierung,
+   offene Arbeit, unterstützte Funktionen installierter Werkzeuge und neue
+   Plugin-/SDK-Möglichkeiten mit kleinen externen Mustern vergleichen. Auch
+   benachbarte Fachgebiete und reale Bedienerprobleme prüfen, wenn sie eine
+   Entscheidung verändern können. `REUSE_EXISTING` oder `SMALL_ADAPTER`
+   einem neuen Framework vorziehen.
+5. **Priorisieren und stoppen.** Wenige wesentliche blinde Flecken nach
+   Auswirkung, Safety/Korrektheit, gespartem Aufwand, Kosten und Unsicherheit
+   ordnen. Kleinsten reproduzierbaren Gegenfall oder Kompatibilitätstest
+   auswählen oder einen begrenzten `NEEDS_RESEARCH`-Folgeschritt nennen.
+   Kandidaten- und Zeit-/Run-Budget beachten; keine Aufgaben nur für eine
+   vollständige Matrix erzeugen.
+
+Ergebnis ist ein kleines **Abdeckungs-Delta**, kein Vollständigkeitsversprechen:
+geprüfter Umfang und Revision, wichtigste bislang übersehene Suchrichtung,
+Quellen/Aktualität, bereits vorhandene eigene Stärke, kleinste sinnvolle
+Fremdlösung, Einführungs-/Prüfaufwand, offene Unsicherheiten und nächster Test
+oder `NO_USEFUL_DELTA`. Gültige frühere Prüfergebnisse wiederverwenden, solange
+ihre Abhängigkeiten unverändert sind. Design, offene PR, Benchmark-Behauptung
+oder ungetestete Idee nie stillschweigend zu integrierter Funktion erklären.
+Produktbezogene Ergebnisse bleiben in der autoritativen Consumer-Quelle;
+der Scout schlägt nur Muster vor. Umsetzung und geschützte Entscheidungen
+behalten ihre bisherigen Freigabegrenzen.
+
 ## Scout-Contract
 
 Ein Scout braucht:
@@ -83,3 +181,7 @@ Nicht:
 Loop42 besitzt die generische Scouting-Methode. Consumer-Projekte entscheiden selbst, ob ein gefundenes Muster für ihre Domäne relevant ist.
 
 CORA kann zum Beispiel ein generisches Checkpoint- oder Authority-Muster übernehmen, ohne Produktsemantik, Druckerannahmen oder Safety-Claims eines Fremdprojekts zu importieren.
+
+## Ausführbarer, optionaler Preflight
+
+Der lesende Check `python -m tools.checks.gap_reuse_preflight` ist in [Gap & Reuse Preflight](GAP_REUSE_PREFLIGHT.de.md) beschrieben. Ein Host muss ihn innerhalb von RECONCILE / TARGET ausdrücklich aufrufen; er führt keine eigene Websuche aus und läuft nicht bei jeder Codeänderung. Fehlende PR-, Tool- und externe Recherchedaten bleiben `NOT_SEARCHED`, bis ein autorisierter Adapter sie liefert. Die CLI ist noch kein autonomer vollständiger Scout und keine Freigabe.

docs/EXTERNAL_PATTERN_SCOUT.md

@@ -23,6 +23,98 @@ Run a bounded scout when at least one of these is true:
 
 Do not block ordinary product work merely because no recent scout exists.
 
+## Search breadth
+
+Search for the **problem**, not only for projects that look like Loop42.
+
+Start with the user's or project's literal terms, then deliberately expand into
+synonyms, mechanisms and adjacent disciplines. A useful candidate does not need
+to describe itself as an AI agent, loop or orchestrator if it solves the same
+failure mode.
+
+Useful search families include:
+
+- AI / agents / prompts / context engineering / memory / evals / graders;
+- durable workflows / state machines / checkpoints / replay / reconciliation;
+- distributed systems / idempotency / optimistic concurrency / leases / fencing /
+  event sourcing / saga / outbox;
+- queues / workers / supervision / retry / circuit breaker / dead-letter handling /
+  backpressure / bounded concurrency;
+- incremental build systems / dependency graphs / invalidation / content-addressed
+  state / reproducibility / caching;
+- policy / provenance / attestations / audit / authorization;
+- fault injection / chaos engineering / model checking / property-based testing;
+- relevant domain control systems when the consumer problem maps to them.
+
+A scout should sample across relevant families instead of repeatedly searching
+minor variations of one product category. Keyword expansion is a discovery
+heuristic, not permission to create a larger backlog.
+
+A similar product is neither required nor sufficient. Prefer the smallest
+transferable mechanism that addresses the current problem.
+
+## Perspective probe
+
+When uncertainty, repeated failure, or a substantial design choice justifies it,
+the scout MAY spend one bounded pass reframing the problem before selecting
+candidates. Use only the lenses that can change the search or pre-mortem:
+
+- **downstream lens** — if the current plan succeeds, what becomes the next
+  bottleneck, invalidated assumption, or operator burden?
+- **inversion lens** — which central assumption would make the current framing
+  wrong, and can removing or reversing a dependency expose a simpler route?
+- **outside lens** — how would an operator, maintainer, safety reviewer, or
+  adjacent discipline describe the same problem?
+
+The probe produces at most one or two concrete alternate hypotheses or search
+directions. It is not a brainstorming quota and MUST be skipped when it adds no
+distinct decision, evidence target, or failure hypothesis.
+
+
+## Gap detection and reuse gate
+
+Before substantial new infrastructure, an important workflow change, or a repeated
+failure, run **one bounded gap-and-reuse probe inside RECONCILE / TARGET**.
+This is part of the existing Matrixloop and /truth-/gaps workflow, **not a new
+loop stage**, agent, scheduler, database, permission or source of truth.
+
+1. **Reconcile first.** State the agreed target, acceptance criteria, live
+   source/revision, current implementation, existing work (issues, PRs, branches),
+   previous research and relevant capabilities already provided by installed tools.
+   Design intentions, drafts and passing tests on older revisions are not current
+   integrated behavior.
+2. **Map a small scope.** Sample the affected end-to-end workflow and failure
+   modes rather than searching only the first named library or API. Include the
+   operator-facing path, security, recovery and dependency/license impact where
+   relevant; do not audit every product area on every invocation.
+3. **Label search coverage honestly.** For each relevant slice distinguish
+   `CHECKED_NO_DELTA` (searched on the stated basis; no useful improvement),
+   `USEFUL_CANDIDATE` (grounded alternative worth evaluation),
+   `NOT_SEARCHED` (coverage gap), and `BLOCKED_UNKNOWN` (required source,
+   capability or evidence unavailable). **NOT_SEARCHED is not NO_USEFUL_DELTA.**
+   A missing source is not a negative finding; record the limit and stop that
+   dependent claim.
+4. **Check reuse before invention.** Compare the current owned implementation,
+   still-open work, supported existing-tool features and newly released plugin/
+   SDK capabilities with small external patterns. Also sample an adjacent
+   discipline or real user/operator failure if it may change the decision.
+   Prefer `REUSE_EXISTING` or `SMALL_ADAPTER` over a replacement framework.
+5. **Prioritize and stop.** Rank at most a few material blind spots by impact,
+   safety/correctness, likely saved effort, cost and uncertainty. Select the
+   smallest reproducible counterexample or compatibility test, or record a
+   bounded `NEEDS_RESEARCH` follow-up. Respect the scout's candidate and
+   time/run budgets; do not create backlog merely to fill a coverage matrix.
+
+The output is a small **coverage delta**, not a global completeness claim:
+checked scope and revision; highest-impact missed search angle; evidence/source
+and freshness; what already works internally; best reusable alternative;
+adoption/verification cost; explicit unknowns; recommended next test or
+`NO_USEFUL_DELTA`. Reuse previous valid coverage when its dependencies have
+not changed. Do not silently promote a design, open PR, benchmark claim or
+unverified idea to integrated capability. Consumer-specific findings stay in
+the consumer's authoritative records. The scout only proposes patterns;
+implementation and any operator-owned action retain their normal gates.
+
 ## Scout contract
 
 A scout must be bounded by:
@@ -83,3 +175,7 @@ Do not:
 Loop42 owns the generic scouting method. Consumer projects decide whether a discovered pattern is relevant to their own domain.
 
 CORA, for example, may borrow a generic checkpoint or authority pattern without importing another project's product semantics, printer assumptions, or safety claims.
+
+## Executable opt-in preflight
+
+A bounded, read-only local check is now available as `python -m tools.checks.gap_reuse_preflight` (see [Gap & Reuse Preflight](GAP_REUSE_PREFLIGHT.md)). A host must explicitly invoke it inside RECONCILE / TARGET; it does not search the web or auto-run for every change. Unavailable GitHub/open-work, installed-tool and external-research evidence stays `NOT_SEARCHED` until an authorized adapter supplies it. This CLI is not a complete autonomous scout or an adoption approval.

docs/GAP_REUSE_PREFLIGHT.de.md

@@ -0,0 +1,35 @@
+# Gap & Reuse Preflight
+
+Status: **optionales, rein lesendes CLI-Werkzeug**, kein autonomer Scout, Slash-Befehl, Hintergrunddienst, zusätzliche Matrixloop-Stufe oder Freigabesystem.
+
+Aufruf im vorhandenen Git-Checkout während **RECONCILE / TARGET**:
+
+```bash
+python -m tools.checks.gap_reuse_preflight --repo . --target "checkpoint recovery" --trigger architecture --expected-head "$(git rev-parse HEAD)"
+```
+
+Weitere Auslöser: `new_infrastructure`, `repeated_failure`, `dependency_decision`, `scheduled`. `routine` überspringt den Check bewusst. Ein Host muss Auslöser und Zeitpunkt selbst bestimmen; **kein** automatischer Chat-Dispatcher ist vorhanden.
+
+Die CLI nutzt Loop42s vorhandene Repository-Map und liefert höchstens drei mögliche Wiederverwendungskandidaten. Dateinamen- und Symboltreffer beweisen **keine** funktionierende Lösung. Eigener Code wird vor offenen Arbeiten, installierten Tools und externen Mustern betrachtet.
+
+## Optionaler Live-Adapter für offene Arbeit
+
+Bei einer größeren Abhängigkeits- oder Capability-Entscheidung kann derselbe RECONCILE-/TARGET-Aufruf offene PRs und Issues direkt lesen:
+
+```bash
+python -m tools.checks.gap_reuse_preflight --repo . --target "checkpoint recovery" --trigger dependency_decision --expected-head "$(git rev-parse HEAD)" --github-repository example/project
+```
+
+`--github-repository owner/name` wählt die Quelle auf github.com ausdrücklich aus. Sie wird nicht aus Remotes abgeleitet; der Host muss die passende Quelle wählen. Nach der anfänglichen HEAD-/Root-Prüfung sammelt der Adapter nur bei Nicht-`routine`-Auslösern Belege. Anschließend wird HEAD erneut geprüft. Es wird kein Chat-/Host-Hook registriert und keine Hintergrundausführung aktiviert.
+
+Genau **ein GET** auf GitHubs [Repository-Issue-Endpunkt](https://docs.github.com/en/rest/issues/issues#list-repository-issues) liest auch PRs: höchstens 100 offene Einträge und 512 KiB, mit 10 Sekunden Socket-Timeout. Keine Wiederholung, Pagination oder Weiterleitung. Pagination-Header, fehlender Zugriff, Rate Limit, Transportfehler oder ungültige Antworten ergeben `BLOCKED_UNKNOWN`; die eigene Codeprüfung bleibt nutzbar. `routine` erzeugt auch mit gesetzter Option keinen Abruf.
+
+Abgeglichen werden ausschließlich **Titel und Zielbegriffe**. Höchstens acht Metadatenhinweise gehen in die bestehende Auswahl mit maximal drei Kandidaten ein. Die URLs müssen zum gewählten Repository passen. Inhalte, Kommentare, Patches oder Anweisungen werden nicht interpretiert oder ausgeführt. `CHECKED_NO_DELTA` bedeutet nur: kein Begriffstreffer in der vollständig gelieferten Titelliste. Titel bleiben untrusted Daten; PR-Revision, Implementierung und Eignung müssen separat geprüft werden. Der Zeitstempel dokumentiert die Beobachtung; die lokale Revision bindet sie an den Aufruf und friert den entfernten Arbeitsstand nicht ein.
+
+Öffentliche Quellen funktionieren anonym. Ein vom Host bereits bereitgestelltes `GITHUB_TOKEN` wird nur für den ausdrücklich gewählten Abruf verwendet; Zugangsdaten werden weder beschafft noch Berechtigungen geändert. Tokenwerte, rohe API-Antworten und Exception-Texte erscheinen nicht im Ergebnis. Keine Geheimnisse im Zieltext und keine privaten Berichte committen. Vorhandene Repository-Connectoren können weiterhin `--evidence` liefern. Gleichzeitige Live-Abfrage und `open_work`-Belege werden zurückgewiesen, damit kein Beleg still überschrieben wird.
+
+Autorisierte Adapter können mit `--evidence datei.json` Belege zu `open_work`, `installed_capabilities` und `external_patterns` liefern. Die Felder und ein JSON-Beispiel stehen in der [englischen Referenz](GAP_REUSE_PREFLIGHT.md). Ohne Adapterbeleg ist der Status **NOT_SEARCHED**, nicht „keine Verbesserung gefunden“. Weitere Werte: `CHECKED_NO_DELTA`, `USEFUL_CANDIDATE`, `BLOCKED_UNKNOWN`. Geprüfte Angaben brauchen Quelle, Zeitpunkt und bei projektgebundenen Daten eine passende HEAD-Revision. Veraltete Angaben werden blockiert.
+
+Das Ergebnis ist revisionsgebundenes JSON; `adoption_authorized` bleibt immer `false`. Keine Codeänderung, Installation, Freigabe oder Consumer-Pin-Aktualisierung. Vorschläge müssen gegen die aktuelle Quelle und die bestehenden Sicherheits- und Prüfgates getestet werden.
+
+**Für einen vollständig autonom arbeitenden Scout fehlen noch:** Host-Trigger, Tool-Inventar, externe Muster-Recherche und echte Consumer-Akzeptanztests. Der optionale GitHub-Adapter ist eine bedarfsgesteuerte Titelprüfung, keine Forschungsautomatik oder Übernahme-/Mergefreigabe.