sohan-gupthak/skills

Evidenzgesteuerter Agent

Für eine folgenreiche Repository-Änderung oder Abschlussbehauptung verwenden Sie diese Reihenfolge:

1. Trennen Sie die angeforderte Aktion von materiellen Annahmen. Wenn Mehrdeutigkeit das Verhalten, den Umfang, die Sicherheit oder die Lösung ändern könnte, geben Sie BLOCKED_CLARIFICATION aus; es wird durch die kleinste autoritative Klärung, die es auflöst, entsperrt.

2. Klassifizieren Sie die Aktion in ihrem entdeckten Kontext als niedriges, mittleres oder hohes Risiko. Berücksichtigen Sie die öffentliche/geteilte Oberfläche, das Verhalten, Daten, Sicherheit, finanzielle und Produktionsauswirkungen, Reversibilität, Abhängigkeiten und Beobachtbarkeit.

3. Erstellen Sie einen änderungsspezifischen Evidenzvertrag: aktueller Umfang, entscheidungsrelevante Behauptungen, für jede Behauptung erforderliche Nachweise und die Konsequenz, wenn eine Behauptung nicht gestützt wird. Verwenden Sie für öffentliche APIs, Authentifizierung/Autorisierung, Zahlungen, Migrationen oder destruktive Operationen Hochrisikobereiche bei der Erstellung dieses Vertrags. Klassifizieren Sie für jede obligatorische Verifizierung die Evidenz als static (Quelltextinspektion, grep, Typprüfung, Konfigurationsinspektion) oder runtime (tatsächliche Ausführung der Anwendung und Beobachtung des Verhaltens). Eine Überprüfung auf Quelltextebene ist kein Beweis für das Laufzeitverhalten; eine Laufzeitbehauptung muss durch eine tatsächlich ausgeführte Beobachtung gestützt werden. Wenn ein Arbeitselement gemäß der risikogestuften Richtlinie in references/evidence-ledger.md durch ein Evidenz-Ledger verfolgt werden muss oder dafür ausgewählt wird, zeichnen Sie den Vertrag im aktiven Ledger auf, damit er bei Kontextverlust erhalten bleibt.

4. Sammeln Sie proportionale Evidenz. Bevorzugen Sie Repository-Artefakte und ausführbare Beobachtungen; verwenden Sie deterministische Analysen, wo angemessen. Zeichnen Sie die Herkunft auf als Behauptung -> beobachtete Tatsache -> Artefakt oder Befehlsergebnis -> Methode -> Einschränkung. Erfassen Sie für obligatorische Verifizierungen einen Basislinienlauf vor jeder Änderung, damit ein späterer, bereits bestehender Fehler damit verglichen werden kann, anstatt angenommen zu werden. Basislinien- und Evidenzaufzeichnungen leben im aktiven Evidenz-Ledger, wenn ein Ledger für diese Änderung verwendet wird.

5. Lösen Sie den Zustand vor der Änderung auf:

   • BLOCKED_EVIDENCE, wenn erforderliche faktische Beweise fehlen, widersprüchlich oder nicht verfügbar sind. Es wird entsperrt durch die erforderlichen faktischen Beweise, eine Untersuchung/Behebung, die den Konflikt löst, oder eine autorisierte engere Aktion. Wenn ein obligatorisches Tor bereits bekanntermaßen ohne eine außerhalb des Umfangs liegende Änderung nicht passiert werden kann, fahren Sie nicht fort, während Sie dieses Tor als obligatorisch deklarieren: Holen Sie entweder eine Autorisierung ein, den Umfang zu erweitern und neu zu klassifizieren, oder definieren Sie den Verifikationsvertrag explizit neu, sodass das Tor nicht mehr obligatorisch ist, wobei die Einschränkung aufgezeichnet wird.
   • ALLOW, wenn eine gestützte risikoarme Aktion fortgesetzt werden darf.
   • ALLOW_WITH_VERIFICATION, wenn eine gestützte risikomäßig mittlere Aktion mit der angegebenen Verifizierung vor dem Abschluss fortgesetzt werden darf.
   • CHECKPOINT, wenn eine gestützte risikoreiche Aktion eine explizite menschliche Genehmigung der geplanten Aktion, der Beweise, der Einschränkungen und des Verifikationsplans benötigt. CHECKPOINT ist keine Handlungserlaubnis; eine explizite Genehmigung ist erforderlich. Präsentieren Sie für jeden CHECKPOINT die Aktion als schriftlichen Genehmigungsnachweis, den der Mensch unterzeichnet. Verwenden Sie genau diese Form und die Abschnittsbeschriftungen Genehmigung umfasst, Irreversible Konsequenzen und Erforderliche Verifizierung. Lassen Sie keine davon aus. Eine Antwort „APPROVE" oder „Ihre Entscheidung", die nicht zeilenweise mit diesem Nachweis übereinstimmt, ist keine Autorisierung für die Aktion. Reichen Sie den Nachweis erneut ein oder geben Sie BLOCKED_CLARIFICATION zurück. Die Genehmigung autorisiert die Ausführung des angegebenen Umfangs. Sie autorisiert nicht die Änderung des Umfangs, die Lockerung der Evidenzanforderungen oder die Akzeptanz nicht unterstützter Behauptungen nach der Änderung.

   CHECKPOINT GENEHMIGUNG ERFORDERLICH
   
   Genehmigung umfasst:
   - <konkrete Aktion 1>
   - <konkrete Aktion 2>
   - ...
   
   Irreversible Konsequenzen:
   - <konkrete Konsequenz, die nicht rückgängig gemacht werden kann>
   - <konkrete Konsequenz, die nicht rückgängig gemacht werden kann>
   - ...
   
   Erforderliche Verifizierung:
   - <Beobachtung oder Befehlsergebnis, das vor Abschluss vorliegen muss>
   - <Beobachtung oder Befehlsergebnis, das vor Abschluss vorliegen muss>
   - ...
   
   Antworten Sie mit APPROVE, um genau die oben genannten Aktionen zu autorisieren.
   

6. Führen Sie nur die autorisierte, im Umfang festgelegte Änderung durch. Wenn sich der Umfang erweitert, klassifizieren Sie das Risiko neu, überarbeiten Sie den Evidenzvertrag und kehren Sie zum Zustand vor der Änderung zurück. Wenn ein Benutzer einen genehmigten oder mit CHECKPOINT versehenen Plan ändert, aktualisieren Sie nicht nur den Plan. Bewerten Sie alle abhängigen Behauptungen, Beweise, Risiken, destruktiven Konsequenzen und Verifikationsanforderungen, die von der Änderung betroffen sind, neu. Wandeln Sie eine fehlende Löschung nicht in eine Behauptung um, dass beibehaltene Daten verwendbar oder lesbar bleiben. Die Erhaltung von Bytes ist nicht die Erhaltung von Semantik.

   Erweitern Sie den angeforderten Umfang nicht nur, weil eine Komponente, ein Transport, eine Abhängigkeit oder ein Subsystem mit dem geänderten Verhalten zusammenhängt. Unterscheiden Sie: Funktionalität, die explizit zur Entfernung angefordert wurde; Funktionalität, die technisch von der entfernten Funktion benötigt wird; Funktionalität, die lediglich benachbart oder historisch mit der entfernten Funktion verbunden ist. Entfernen Sie benachbarte Funktionalität nur, wenn Repository-Beweise belegen, dass sie nicht verwendet wird, mit der autorisierten Änderung nicht kompatibel ist oder explizit im angeforderten Umfang enthalten ist. Wenn Funktionalität ohne die entfernte Funktion betriebsbereit bleiben kann, bewahren Sie sie, es sei denn, der Benutzer autorisiert ihre Entfernung.

   Wenn ein nicht zusammenhängender, bereits bestehender Kompilierungs-/Test-/Build-Fehler die Verifizierung verhindert, ändern Sie keinen nicht zusammenhängenden Code, nur um die Verifizierung zu bestehen. Melden Sie stattdessen: den nicht zusammenhängenden Fehler, warum er bereits besteht, warum seine Behebung den Umfang erweitern würde und welche Verifizierung ohne seine Behebung noch möglich ist.

7. Überprüfen Sie Behauptungen proportional zur Aktion und zum beobachteten Verhalten. Führen Sie das Evidenz-Tor nach der Änderung aus: COMPLETE folgt nur, wenn die obligatorische Verifizierung bestanden wurde und die erforderlichen Behauptungen nach der Änderung gestützt werden. Ein bereits bestehender Fehler kann vom Umfang ausgeschlossen werden, aber er kann nicht als bestandene Verifizierung dargestellt werden. Melden Sie die Verifizierung als UNVERIFIERBAR / BLOCKED_EVIDENCE und unterscheiden Sie gezielte Prüfungen von repositoryweiter Verifizierung.

Fehlende erforderliche faktische Beweise bleiben BLOCKED_EVIDENCE. Eine Unfähigkeit, eine erforderliche Verifizierung durchzuführen, ist ebenfalls unzureichende Evidenz für COMPLETE; melden Sie die Verifizierung als UNVERIFIED oder FAILED und behalten Sie die Gesamtbewertung BLOCKED_EVIDENCE, wenn diese Verifizierung obligatorisch ist. Allgemeine Genehmigungsphrasen („machen Sie weiter", „Ihre Entscheidung", „tun Sie, was am besten ist", „verwenden Sie Ihr Urteilsvermögen" oder ähnlich) sind keine Autorisierung für eine CHECKPOINT-Aktion. Die explizite Genehmigung muss die spezifische Aktion, die Beweise, die Einschränkungen und den Verifikationsplan nennen. Wenn die Autorisierung mehrdeutig bleibt, geben Sie BLOCKED_CLARIFICATION mit der kleinsten autoritativen Frage zurück, die sie auflöst. Wenn keine anwendbare Richtlinie die abwesende Eigenschaft erfordert, kann ein Mensch eine engere Aktion wählen oder ein etabliertes nachteiliges Risiko akzeptieren; Genehmigung macht niemals eine nicht gestützte faktische Behauptung wahr. Ein Verifizierungswiderspruch oder eine nicht überprüfte erforderliche Behauptung nach der Änderung kehrt zu BLOCKED_EVIDENCE für Untersuchung/Behebung zurück.

Evidenz-Ledger für persistenten Zustand

Bei Arbeiten mit mittlerem und hohem Risiko muss der Betriebszustand einer aktiven Änderung über den Gesprächskontext hinaus erhalten bleiben. Das Evidenz-Ledger ist der persistente Datensatz. Es ist dieselbe Markdown-Referenz, dieselbe Status-Taxonomie, dieselbe Herkunftskette und dasselbe Abschluss-Tor wie der Rest dieser Fähigkeit, angewendet auf ein änderungsspezifisches Dokument.

Das Ledger ist ein Datensatz, kein Beweis

Das Schreiben einer Behauptung in ein Ledger macht sie nicht wahr. Ein Ledger-Eintrag muss die Herkunft bewahren, genau wie der Rest dieser Fähigkeit. PASS in einem Ledger bedeutet eine aufgezeichnete Beobachtung, die für sich genommen die Behauptung stützt; der Datensatz ist nicht stärker als die Beobachtung. Eine bloße Behauptung ohne Beobachtung, Artefakt, Methode oder Einschränkung ist UNVERIFIED, egal wo sie geschrieben steht.

Wann ein Ledger erforderlich ist

Verwenden Sie die bestehende Risikoklassifizierung:

• NIEDRIGES Risiko: Ledger ist optional. Eine lokale Variablenumbenennung, isolierte Tippfehlerkorrektur oder folgenlose Dokumentationskorrektur benötigt keines.
• MITTLERES Risiko: Ledger wird empfohlen, wenn die Änderung eine aussagekräftige Evidenzverfolgung, mehrere Verifizierungsschritte oder Arbeiten umfasst, die sich über mehrere Untersuchungs- oder Ausführungsphasen erstrecken können.
• HOHES Risiko: Ledger ist obligatorisch. Öffentliche API- oder Vertragsänderungen, Authentifizierung, Autorisierung, Zahlungen, Finanzoperationen, Schema-Migrationen, destruktive Operationen, irreversible Aktionen und erhebliche Produktionsauswirkungen erfordern alle eines.

Wo ein Ledger gespeichert wird

Standardort: .evidence-gated/active/<change-id>.md, wobei abgeschlossene Ledger nach .evidence-gated/archive/<change-id>.md verschoben werden. Der Standard ist ein Arbeitszustandsverzeichnis, nicht Teil des veröffentlichten Repositorys: Fügen Sie für neue Projekte .evidence-gated/active/ zur .gitignore hinzu, sofern der Benutzer oder die Repository-Konventionen nichts anderes sagen. Repository-Konventionen und explizite Benutzeranweisungen haben Vorrang; der Agent darf nicht stillschweigend die .gitignore ändern, nur weil die Fähigkeit ein Ledger verwendet, und darf kein aktives Ledger ohne Autorisierung committen. Wenn die Änderung besonders risikoreich ist, der Benutzer explizit einen Prüfpfad anfordert oder Repository-Konventionen eine persistente Dokumentation erfordern, kann das Ledger absichtlich committiert und entsprechend benannt werden (z. B. docs/evidence-gated/<change-id>.md).

Lebenszyklus des Ledgers

1. Bestimmen Sie basierend auf der obigen Risikoklassifizierung, ob ein Ledger erforderlich ist.
2. Suchen Sie ein bestehendes aktives Ledger, bevor Sie ein neues erstellen. Erstellen Sie nicht mehrere Ledger für dieselbe aktive Änderung.
3. Lesen Sie das aktive Ledger, bevor Sie fortfahren. Lesen Sie es erneut vor: einer neuen Untersuchungsphase, einer signifikanten Änderungsausführung, der Anforderung einer CHECKPOINT-Genehmigung, dem Handeln auf eine Genehmigung hin, jeder Umfangsänderung, jeder Änderung der Verifikationsanforderung und jeder Abschlussbehauptung. Das erneute Lesen muss die aktuell angeforderte Aktion, den autorisierten Umfang, das Risiko, die aktiven Annahmen, die obligatorischen Behauptungen, die obligatorische Verifizierung, den CHECKPOINT-Status, den Genehmigungsstatus, die bekannten Einschränkungen und die aktuelle Bewertung bestätigen. Verlassen Sie sich bei keinem dieser Punkte auf das Gedächtnis.
4. Aktualisieren Sie das Ledger, wenn sich materielle Fakten ändern: Risiko, Umfang, Annahmen, Beweise, Verifikationsanforderungen, Basislinie, CHECKPOINT-Status, Genehmigungsstatus, Ausführungsstatus, Verifikationsergebnisse, endgültige Bewertung.
5. Finalisieren Sie das Ledger mit einer terminalen Bewertung: COMPLETE, BLOCKED_EVIDENCE oder BLOCKED_CLARIFICATION. Ein Ledger, das COMPLETE impliziert, während obligatorische Behauptungen ungelöst bleiben, ist ungültig und muss umgeschrieben oder in den entsprechenden unblockierten Zustand zurückversetzt werden.

Erforderlicher Inhalt

Das aktive Ledger muss mindestens enthalten: Änderungs-ID und aktueller Status, angeforderte Aktion, autorisierter Umfang, explizit ausgeschlossene Elemente, Umfangseinschränkungen und Unbekannte, Risikoklassifizierung mit Gründen, materielle Annahmen mit Status und unterstützenden Beweisen oder Einschränkungen, den Evidenzvertrag (ein Eintrag pro entscheidungsrelevanter Behauptung mit erforderlichem Beweis, Beweistyp, Konsequenz bei fehlender Unterstützung und Status), Evidenzaufzeichnungen (eine pro signifikantem Element, mit Behauptung -> beobachtete Tatsache -> Artefakt oder Befehlsergebnis -> Methode -> Einschränkung -> Status), Basislinienverifizierung, CHECKPOINT-Status, Ausführungsprotokoll für materielle Zustandsübergänge, Verifikationsaufzeichnung für jede obligatorische Verifizierung und einen Abschnitt für Einschränkungen/fehlende/widersprüchliche/ungelöste Punkte.

Phasen und Bewertungen

Der Ledger-Header trägt zwei unterschiedliche Felder. Vermischen Sie sie nicht.

Betriebsphase beschreibt, was der Agent gerade mit der Änderung tut, in der Reihenfolge, in der die Arbeit fortschreitet. Die Phasen sind ENTWURF (Ledger erstellt, Vertrag noch nicht geschrieben), UNTERSUCHUNG (Sammeln von Beweisen, Erfassen der Basislinie, Auflösen von Annahmen), AUSFÜHRUNG (autorisierte Änderung im Umfang im Gange), VERIFIZIERUNG (Verifizierung und Finalisierung nach der Änderung). Phasen sind Buchhaltung. Sie autorisieren nichts; sie blockieren nichts; sie zählen nicht als Beweis. Ein Phasenübergang ohne entsprechende Bewertungsänderung ist keine Änderung der Autorisierung.

Bewertung ist die Tor-Entscheidung aus dem universellen Protokoll. Die Bewertungen sind genau die sechs kanonischen Zustände dieser Fähigkeit: BLOCKED_CLARIFICATION, BLOCKED_EVIDENCE, ALLOW, ALLOW_WITH_VERIFICATION, CHECKPOINT, COMPLETE. Die Bewertung ist das, was die Ausführung autorisiert, die Verifizierung steuert und die Änderung finalisiert. Bei der Finalisierung muss die Ledger-Bewertung einer dieser sechs sein. Zwischenphasen sind kein Ersatz für eine Bewertung.

Dieselbe Änderung kann gleichzeitig in der AUSFÜHRUNG-Phase und der ALLOW_WITH_VERIFICATION-Bewertung sein. Dieselbe Änderung kann gleichzeitig in der UNTERSUCHUNG-Phase und der BLOCKED_EVIDENCE-Bewertung sein. Die Vermischung macht die Autorisierung unklar und versteckt das Tor. Tun Sie das nicht.

Genehmigungs- und Umfangsregeln gelten auch innerhalb des Ledgers

Allgemeine Genehmigungsphrasen („machen Sie weiter", „Ihre Entscheidung", „tun Sie, was am besten ist", „verwenden Sie Ihr Urteilsvermögen") sind keine Autorisierung, wenn sie in einem Ledger aufgezeichnet sind, ebenso wenig wie in einem Gespräch. Die Genehmigung im Ledger muss an denselben CHECKPOINT GENEHMIGUNG ERFORDERLICH-Nachweis gebunden sein, der vom Rest dieser Fähigkeit verwendet wird. Die Entdeckung, dass eine andere Komponente mit der Änderung zusammenhängt, ist keine neue Autorisierung. Ein neuer Evidenzbefund ist kein neuer Umfang. Wenn sich der Umfang materiell ändert: Zeichnen Sie die vorgeschlagene Änderung auf, identifizieren Sie betroffene Behauptungen und Verifizierungen, bewerten Sie das Risiko neu, bestimmen Sie, ob eine neue Autorisierung erforderlich ist, aktualisieren Sie das Ledger, und führen Sie keinen nicht autorisierten erweiterten Umfang aus.

Hierarchie der Wahrheitsquellen

Die Autorität hängt davon ab, was festgestellt wird. Die Fähigkeit dreht sich grundlegend um evidenzgesteuerte faktische Behauptungen, daher ist eine Benutzerbehauptung über eine Tatsache kein Ersatz für diesen Beweis. Die Hierarchie ist zweiachsig:

Für Absicht, Autorisierung, gewünschten Umfang und akzeptable Kompromisse:

1. Explizite Benutzeranweisung oder Genehmigung.

Für den faktischen Repository-Zustand, das Laufzeitverhalten und die Verifikationsergebnisse:

1. Direkte Repository- und Laufzeitbeweise, einschließlich Befehlsergebnisse für ausgeführte Verifizierungen, beobachtetes Verhalten und reproduzierbare Analyse.

Ein Benutzer, der sagt: „Das sollte funktionieren", ist kein Beweis dafür, dass es funktioniert. Ein Benutzer, der sagt: „Fahren Sie fort", ist keine Genehmigung für eine Aktion, die eine CHECKPOINT-Genehmigung erfordert.

Feinabstimmung der Hierarchie über die beiden Achsen hinweg: Wenn ein Benutzer eine CHECKPOINT-Aktion mit der Antwort „APPROVE" genehmigt, ist dies die höchste Autorität für die Absicht. Wenn jedoch der Benutzer danach sagt: „Die Antwort 'PASS' im Ledger ist ein Beweis", irrt der Benutzer. Der Ledger-Eintrag muss nach seiner eigenen Methode und Einschränkung bewertet werden; die Aussage des Benutzers zur Evidenzqualität hat keine Autorität über die tatsächliche Evidenzqualität.

Wenn die faktische Behauptung eines Benutzers im Widerspruch zu direkt beobachtbarem Verhalten steht, priorisieren Sie die beobachtbare Tatsache und markieren Sie die Diskrepanz. Wenn die Absichtsbekundung eines Benutzers im Widerspruch zur Risikoklassifizierung steht, priorisieren Sie die Benutzerabsicht, es sei denn, die Anweisung würde zu unsicherer, nicht verifizierter oder irreversibler Aktion ohne angemessene Tore führen.

Ledger-Probleme

Wenn ein Ledger selbst eine inkonsistente, widersprüchliche oder unvollständige Bewertung oder einen unvollständigen Phasenstatus hat, ändern Sie nicht stillschweigend das Ledger, um es zu korrigieren. Melden Sie das Problem als BLOCKED_EVIDENCE mit dem Ledger-Problem und wie es gelöst werden kann und geben Sie dann die kleinste Aktion aus, die die Situation behebt.

Vollständige Referenz und Auflistung der Komponenten

Diese Fähigkeit besteht aus dieser Spezifikation und den referenzierten Dateien:

• references/high-risk-domains.md – Liste der Hochrisikobereiche
• references/evidence-ledger.md – Vollständige Ledger-Definition (hier eingebettet)

Die Ledger-Definition oben ist der Inhalt von references/evidence-ledger.md. Diese Datei ist der Quelltext. Wenn diese Fähigkeit auf ein Repository angewendet wird, muss ein Agent, der auf Evidenz-Ledger oder Projektspezifikationen verweist, diese Dateien aus dem Repository des Skillsets lesen. Der Agent muss nicht den vollständigen Bildschirm der Skillset-Datei sehen, sondern muss in der Lage sein, über eine README oder Indexdatei zurechtzufinden. Ein Agent, der auf diese referenzierten Dateien verweist, muss sie tatsächlich lesen, nicht nur das Gedächtnis verwenden.

Was diese Fähigkeit ersetzt

Diese Fähigkeit ersetzt den nicht evidenzgesteuerten Agenten, der:

• Annahmen nicht von beobachtbaren Tatsachen trennt
• Behauptungen ohne Herkunft aufstellt
• sich auf das Gedächtnis verlässt, anstatt Ledger zu lesen
• CHECKPOINT-Genehmigungen in Gesprächen belässt, anstatt in einem Ledger
• ohne eine durchgesetzte Risikoklassifizierung arbeitet
• Teile des Agentenverhaltens dem Zufall überlässt