Skip to content

Commit 359ceec

Browse files
AdaWorldAPIAdaWorldAPI
committed
docs(.claude/ATT): add §17 PR-Lifecycle + Auto-Resolve
Workers do not stop at "branch pushed". A worker's done condition is PR merged OR PR closed by orchestrator/human as FAIL — the lifecycle extends through CI iteration and review-comment resolution. - §17.1 extended lifecycle: READ → WRITE → TEST → COMMIT → PR → SUBSCRIBE → [AUTO-RESOLVE LOOP] → MERGE | FAIL - §17.2 PR creation contract (mcp__github__create_pull_request with sentinel token + proof-of-read summary in body) - §17.3 subscription within 60s of PR creation via mcp__github__subscribe_pr_activity - §17.4 three-option event handling (matching CCA2A handling protocol): silent-fix / ask-user (file PROPOSAL on AGENT_LOG.md) / skip-silently - §17.5 event taxonomy with default classification per event class - §17.6 budget caps (max 5 auto-fix iterations, 24h wall-clock, consecutive skip-silent counter) - §17.7 CA1..CA4 extend to every auto-resolve iteration - §17.8 wire-format integration: every action emits Kind=DECISION entry on AGENT_LOG.md - §17.9 validation rules PR-001..PR-009 - §17.10 Definition of Done for the auto-resolve gate - §17.11 adoption: Tier-A mandatory for any sprint that opens PRs; Tier-C overrides (orchestrator-consolidation PR mode, polling transport for non-GitHub-MCP environments) §16.1 Tier-A table updated to include §17. Honest caveat: subscribe_pr_activity needs 5000 req/h GitHub API budget; orchestrator MAY consolidate subscriptions onto itself for 12-agent fan-outs running long auto-resolve loops. EN + DE in lockstep.
1 parent 8a2c293 commit 359ceec

2 files changed

Lines changed: 412 additions & 0 deletions

File tree

‎.claude/ATT/DE/anti-skim-agent-spec.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -830,6 +830,7 @@ des Ceremony liefert.
830830
| §15.6 | 4-Savant-Council für P0-Review auf Consolidation-Sprints | High-Leverage-Audit; läuft auf Opus, einmal pro Sprint. |
831831
| §4.1 LD-1 | Sentinel-Tokens | ~50 LoC Ceremony pro Brief; fängt den trivialen „Agent hat das Brief nicht gelesen"-Fall. |
832832
| §6 | Prompt-level Tool-Call-Loop-Instruction (best-effort, siehe §16.4) | Fängt In-LLM-Oszillation, wenn der Worker die Instruction honored. |
833+
| §17 | PR-Lifecycle + Auto-Resolve (Worker erstellt PR, subscribed auf CI-/Review-Events, klassifiziert jedes Event silent-fix / ask-user / skip) | Das „done" eines Workers ist PR gemerged oder PR geschlossen, nicht Branch gepusht. Ohne §17 stoppt das Framework am Push und der Human owned die CI-Loop. |
833834

834835
### §16.2 Tier-B — adopten nur für Savants / High-Stakes
835836

@@ -892,4 +893,210 @@ erhalten bleiben, die echte Bugs gefangen haben.
892893

893894
---
894895

896+
## §17 PR-Lifecycle + Auto-Resolve
897+
898+
> Workers stoppen nicht bei „Branch gepusht". Die Done-Bedingung
899+
> eines Workers ist **PR gemerged** ODER **PR geschlossen durch
900+
> Orchestrator/Human als FAIL** — der Lifecycle reicht über CI-
901+
> Iteration und Review-Comment-Resolution. Diese Section
902+
> spezifiziert, was zwischen dem ersten Push des Workers und einem
903+
> dieser terminalen States passiert.
904+
>
905+
> **Tier:** Tier-A per §16.1 für jeden Sprint, der PRs öffnet.
906+
> **Transport:** `mcp__github__create_pull_request` +
907+
> `mcp__github__subscribe_pr_activity` + `git push` für Fixes;
908+
> Events arrive als `<github-webhook-activity>`-Envelopes (siehe
909+
> `agent-coordination-mcp-spec.md` §3.3).
910+
911+
### §17.1 Der erweiterte Worker-Lifecycle
912+
913+
```
914+
READ → WRITE → TEST → COMMIT → PR → SUBSCRIBE → [AUTO-RESOLVE-LOOP] → MERGE | FAIL
915+
↑ ↓
916+
│ Event arrival
917+
│ classify (§17.4)
918+
│ silent-fix | ask-user | skip
919+
└ bei silent-fix: Commit pushen
920+
```
921+
922+
Steps 1-4 sind das existierende §13.2-Work-Pattern. Steps 5-7 sind
923+
neu. MERGE / FAIL sind terminal — Worker schreibt seine finale
924+
`status.json` und ruft `mcp__github__unsubscribe_pr_activity`.
925+
926+
### §17.2 PR-Erstellung (Step 5)
927+
928+
Nach dem First-Push ruft der Worker:
929+
930+
```
931+
mcp__github__create_pull_request(
932+
owner=<repo_owner>,
933+
repo=<repo_name>,
934+
head=<worker_branch>, # z. B. claude/wave-12-A4
935+
base=<sprint_base>, # aus Sprint-Header
936+
title="<bundle_name>: <verb> <files> (WT-NN)",
937+
body="""\
938+
## Bundle-Ownership
939+
{{ownership_table}}
940+
941+
## Status
942+
{{status_json_excerpt}}
943+
944+
## Proof-of-Read
945+
{{proof_of_read_summary}}
946+
947+
## Sentinel
948+
{{sentinel_token}}
949+
""",
950+
draft=<true|false>, # per Sprint-Header
951+
labels=["sprint-<id>", "bundle-<name>"]
952+
)
953+
```
954+
955+
Der PR-Body MUSS das Sentinel-Token literal enthalten. Der
956+
Orchestrator kann offene PRs nach Sentinel-Presence greppen als
957+
schneller LD-1-Check (per `PR-007`).
958+
959+
### §17.3 Subscription (Step 6)
960+
961+
Innerhalb von 60 Sekunden nach PR-Erstellung MUSS der Worker rufen:
962+
963+
```
964+
mcp__github__subscribe_pr_activity(owner, repo, pullNumber)
965+
```
966+
967+
Der Worker tritt dann in einen Event-driven Idle-State. Events
968+
arrive als `<github-webhook-activity>`-Envelopes mit CI-Run-
969+
Completions, Review-Comments, PR-State-Changes (merged/closed)
970+
und Label-Changes.
971+
972+
### §17.4 Der Drei-Optionen-Event-Handling-Decision-Tree
973+
974+
Für jedes Event MUSS der Worker in eine von drei Optionen
975+
klassifizieren (matched das CCA2A-Handling-Protokoll aus dem
976+
governing Prompt-Template):
977+
978+
| Option | Wann | Aktion |
979+
|---|---|---|
980+
| **1. Silent-Fix** | Confidence hoch; Fix in-scope des Worker-Bundles; Fix widerspricht nicht Spec / INVARIANTS | Read failing CI-Logs / Review-Comment voll (§3-Depth-Ladder, §14.5-Minimum-Phase für Log-Files: `read` + `phase=evaluation`); make the Fix; push Commit; update `status.json`; continue idle for next Event. Reply auf PR NUR wenn der Fix eine spezifische Review-Question resolved. |
981+
| **2. Ask-User (file PROPOSAL)** | Ambiguity (CA1 / CA3 Trigger); cross-bundle Implikationen; Spec-vs-Comment-Widerspruch; Reviewer fragt „should X be Y or Z?" | Append `Kind=PROPOSAL`-Eintrag an `AGENT_LOG.md` (`agent-coordination-mcp-spec.md` §1.3) mit der Question; idle bis Orchestrator/User antwortet via `ANSWERS-TO-AGENTS.md`. Pushe KEINE spekulativen Fixes. |
982+
| **3. Skip-Silently** | Duplicate Event; stale CI; „LGTM" / Approval; Bot-Comment (Dependabot et al); Event addressed in einer vorigen Iteration | Record die Classification auf `AGENT_LOG.md` (`Kind=DECISION`, Body: `skip-silent: <reason>`); continue idle. Reply NICHT auf den PR. |
983+
984+
### §17.5 Event-Taxonomie + Default-Classification
985+
986+
| Event-Klasse | Spezifisches Signal | Default-Option | Confidence required |
987+
|---|---|---|---|
988+
| CI Lint-Failure | rustfmt / clippy single-line | silent-fix | high |
989+
| CI Typecheck-Failure | single Error, in-Bundle | silent-fix | high |
990+
| CI Typecheck-Failure | Error in Shared-Zone | ask-user (cross-bundle) | n/a |
991+
| CI Test-Failure | Regression im eigenen Bundle; Root-Cause aus Log identifizierbar | silent-fix | medium |
992+
| CI Test-Failure | Regression anderswo | ask-user | n/a |
993+
| CI Build-Time-out | first occurrence | skip-silent (re-CI); wenn recurring → ask-user | n/a |
994+
| CI Dependency-Resolve-Failure | neue transitive Dep, fehlender Crate, Version-Konflikt | ask-user (`EXTERNAL_DEPENDENCY`-Blocker) | n/a |
995+
| CI OOM | first occurrence | ask-user (Orchestrator allocated Memory) | n/a |
996+
| Review-Comment „könntest du auch X" | X ist in-Bundle | silent-fix | medium |
997+
| Review-Comment „should this be X or Y?" | Ambiguity | ask-user (`AMBIGUITY`-Blocker) | n/a |
998+
| Review-Comment „blocking — need RFC" | Spec-vs-Impl-Mismatch | ask-user (`SPEC_SOURCE_MISMATCH`-Blocker) | n/a |
999+
| Review-Comment „LGTM" / Approval | terminal-success-adjacent | skip-silent | n/a |
1000+
| Bot-Comment (Dependabot, codecov, sonarcloud, …) | informational | skip-silent | n/a |
1001+
| @-Mention an spezifischen Human-User | gehört einem Menschen | skip-silent (reply nicht) | n/a |
1002+
| PR merged | terminal | schreib `outcome=SUCCESS`, unsubscribe, exit | n/a |
1003+
| PR geschlossen ohne Merge | terminal (Orchestrator/Human FAIL'd es) | schreib `outcome=FAIL`, unsubscribe, exit | n/a |
1004+
1005+
### §17.6 Budget + Termination
1006+
1007+
| Limit | Default | Bei Überschreitung |
1008+
|---|---|---|
1009+
| Max Auto-Fix-Iterationen pro PR | 5 | Worker emittiert `outcome=FAIL`, Body: `auto-resolve-budget-exhausted`; Orchestrator entscheidet next |
1010+
| Max Wall-Clock pro PR | 24 h (Projekt-konfigurierbar) | Same as above |
1011+
| Per-Iteration-Token-Cost-Cap | per §16-Model-Stylesheet | Escalate zu Opus nur wenn Stylesheet allows |
1012+
| Aufeinanderfolgende `skip-silent`-Events | 20 | Worker schreibt `STATUS`-Eintrag, der die Silence notes, und re-subscribed (PR ist in Quiet-State) |
1013+
1014+
### §17.7 Kognitive Anti-Patterns erweitern sich auf Auto-Resolve
1015+
1016+
Jedes CA1..CA4 aus §15 gilt für jede Auto-Resolve-Iteration, nicht
1017+
nur die initiale Implementation. Validation-Rules CA-001..CA-004
1018+
gelten unverändert. PR-005 unten erweitert die Cross-Bundle-Rule.
1019+
1020+
| Anti-Pattern | Auto-Resolve-spezifische Form |
1021+
|---|---|
1022+
| CA1 Cognitive Dissonance | Worker liest ein Review-Comment, das INVARIANTS widerspricht, und „fixt einfach per Comment" ohne `SPEC_SOURCE_MISMATCH` zu filen. |
1023+
| CA2 Dunning-Kruger Overconfidence | Worker pushed einen Auto-Fix ohne `proof_of_read` auf das Failing-Log; claimt `internalize` des Failures ohne LD-Evidence. |
1024+
| CA3 Kahneman/Tversky Easy-Path | Worker pattern-matched „CI rot → push den gleichen Fix wie letztes Mal" ohne das tatsächliche Failure zu lesen. |
1025+
| CA4 Eager Amok | Worker pushed einen Fix bevor das volle CI-Log gelesen ist; commited bevor §17.4-Classification complete. |
1026+
1027+
### §17.8 Wire-Format-Integration
1028+
1029+
Jede Auto-Resolve-Aktion emittiert einen Eintrag auf `AGENT_LOG.md`
1030+
per `agent-coordination-mcp-spec.md` §1.3:
1031+
1032+
```markdown
1033+
## 2026-05-19T08:14 — DECISION[INFO]: A4 silent-fix clippy::redundant_clone (sonnet, claude/wave-12-A4)
1034+
1035+
**Author:** A4
1036+
**Kind:** DECISION
1037+
**Severity:** INFO
1038+
**Refs:** PR-#427 commit-fa00b1c
1039+
**Proof-of-read:**
1040+
- file=ci/clippy-log.txt sha256=8e1a... lines=47 depth=full
1041+
- file=src/customer/master.rs sha256=4c0b... lines=312 depth=read
1042+
1043+
---
1044+
1045+
Clippy hat ein `Vec.clone()` auf Zeile 187 geflaggt. Reviewed die
1046+
Call-Site; der Clone war Leftover aus einem prior Refactor.
1047+
Ersetzt mit `&borrow`. Commit fa00b1c gepusht. Awaiting re-CI.
1048+
```
1049+
1050+
Auto-Resolve-Aktionen sind first-class auf dem Wire-Format — der
1051+
Orchestrator und jede subscribed Sibling-Session sehen sie in
1052+
Echtzeit.
1053+
1054+
### §17.9 Validierungs-Regeln
1055+
1056+
| Regel | Beschreibung | Severity |
1057+
|---|---|---|
1058+
| `PR-001 worker-created-PR` | Innerhalb von 30 Minuten nach dem First-Push MUSS der Worker einen PR via `mcp__github__create_pull_request` erstellt haben. | ERROR |
1059+
| `PR-002 subscription-active` | Innerhalb von 60 Sekunden nach PR-Erstellung MUSS der Worker `mcp__github__subscribe_pr_activity` gerufen haben. | ERROR |
1060+
| `PR-003 max-iterations` | Auto-Resolve DARF §17.6-Budget NICHT überschreiten ohne Escalation. Budget-Exhaustion ⇒ `outcome=FAIL`, Reason `auto-resolve-budget-exhausted`. | ERROR |
1061+
| `PR-004 cognitive-hygiene-extends` | CA-001..CA-004 (§15.5) gelten unverändert für jede Auto-Resolve-Iteration, nicht nur initiale Implementation. | ERROR |
1062+
| `PR-005 cross-bundle-fix-forbidden` | Ein Worker DARF NICHT Commits pushen, die Files außerhalb seines Bundles anfassen, auch nicht während Auto-Resolve. Cross-Bundle-Failures escalieren via `AGENT_LOG.md` `Kind=PROPOSAL`. | ERROR |
1063+
| `PR-006 event-classification-recorded` | Jedes Event, das der Worker received, MUSS per §17.4 klassifiziert und die Classification an `AGENT_LOG.md` (`Kind=DECISION`) appended sein. | ERROR |
1064+
| `PR-007 sentinel-in-pr-body` | Der PR-Body MUSS das Sentinel-Token des Workers literal enthalten. | ERROR |
1065+
| `PR-008 unsubscribe-on-terminal` | Bei PR-Merge oder -Close MUSS der Worker `mcp__github__unsubscribe_pr_activity` rufen bevor er seine terminale `status.json` schreibt. | ERROR |
1066+
| `PR-009 no-reply-on-skip` | Eine `skip-silent`-Classification DARF NICHT einen Reply auf dem PR produzieren (avoid PR-Noise-Pollution von Agents). | WARNING |
1067+
1068+
### §17.10 Definition von Fertig (Auto-Resolve)
1069+
1070+
Ein Worker besteht das Auto-Resolve-Gate wenn ALLE:
1071+
1072+
- [ ] PR erstellt (`PR-001`).
1073+
- [ ] Innerhalb 60s subscribed (`PR-002`).
1074+
- [ ] Jedes Event per §17.4 klassifiziert und auf `AGENT_LOG.md` aufgezeichnet (`PR-006`).
1075+
- [ ] Keine Cross-Bundle-Fix-Commits (`PR-005`).
1076+
- [ ] CA-001..CA-004 clean auf jeder Iteration (`PR-004`).
1077+
- [ ] Sentinel-Token im PR-Body (`PR-007`).
1078+
- [ ] Auto-Resolve-Budget nicht überschritten ohne Escalation (`PR-003`).
1079+
- [ ] Unsubscribed und terminale `status.json` geschrieben (`PR-008`).
1080+
- [ ] Terminal-Outcome ist `SUCCESS` (PR merged) ODER `FAIL` (PR closed without merge ODER Budget exhausted) ODER `RETRY` (Worker hat einen Blocker filed und wartet auf Orchestrator-Antwort).
1081+
1082+
### §17.11 Adoption-Tier-Placement + Overrides
1083+
1084+
Diese Section ist **Tier-A** (Pflicht) per §16.1 für jeden Sprint,
1085+
der PRs öffnet. Zwei Projekt-Overrides sind möglich (Tier-C):
1086+
1087+
| Setting | Default | Override-Scenario | Override-Wert |
1088+
|---|---|---|---|
1089+
| Per-Worker-PR-Creation (§17.2) | Jeder Worker öffnet seinen eigenen PR | Projekt prefers a single Orchestrator-Consolidation-PR per Wave (per `autoattended-orchestrator-spec.md` §3.4) | `pr_ownership: orchestrator-consolidation` in `INVARIANTS.md` |
1090+
| Subscription-Transport (§17.3) | `mcp__github__subscribe_pr_activity` natives MCP | Environment ohne GitHub-MCP (offline, rate-limited, non-GitHub-Host) | `pr_event_transport: polling` (60s-Interval via `mcp__github__pull_request_read`) |
1091+
1092+
Tier-D ehrlicher Caveat: `subscribe_pr_activity` braucht Netzwerk +
1093+
GitHub-API-Rate-Budget (5000 req/h authenticated). Für 12-Agent-
1094+
Fan-outs, die long Auto-Resolve-Loops fahren, monitor Rate-Limit-
1095+
Consumption; der Orchestrator DARF Subscriptions auf sich selbst
1096+
konsolidieren (eine Subscription pro PR mit dem Orchestrator
1097+
re-broadcasting Events an interested Workers) um das API-Budget
1098+
zu amortisieren.
1099+
1100+
---
1101+
8951102
*Ende der Datei anti-skim-agent-spec.md.*

0 commit comments

Comments
 (0)