diff --git a/README.md b/README.md index b03f95f..b9a105d 100644 --- a/README.md +++ b/README.md @@ -134,3 +134,11 @@ For detailed models, see `backend/LMS/labs/models.py`. ## Full Setup Guide For a comprehensive, step-by-step setup, see the dedicated guide: [SETUP_GUIDE.md](SETUP_GUIDE.md) +--- + +## Validation +Deterministic PR workflow end-to-end validation line (YAS-249). +Deterministic PR workflow end-to-end validation line (YAS-248). +Deterministic PR workflow end-to-end validation line (YAS-248). +Deterministic PR workflow end-to-end validation line (YAS-251). + diff --git a/docs/pr-workflow-comment-failure-retry-policy.md b/docs/pr-workflow-comment-failure-retry-policy.md new file mode 100644 index 0000000..48fe9dc --- /dev/null +++ b/docs/pr-workflow-comment-failure-retry-policy.md @@ -0,0 +1,77 @@ +# PR Workflow Comment Task — Failure-and-Retry Policy + +**Issue:** YAS-180 +**Parent:** YAS-64 — Decompose PR workflow comment task into verifiable steps +**Project:** LMS + +## 1. Purpose + +This document defines how the CTO agent handles failures when executing the PR-workflow comment task. The goal is to: + +- Retry only transient, recoverable failures. +- Cap retries so a single transient fault cannot spin forever. +- Surface terminal failures as visible blockers on the issue, never as silent `done` completions. +- Leave an audit trail in issue comments for every retry and terminal outcome. + +## 2. Scope + +Applies to the comment sub-task of the LMS “Raise PR” workflow, specifically the step where the agent posts a comment to the Paperclip issue summarizing PR evidence (branch, commit, PR URL, verification results). + +## 3. Failure classification + +| Class | Examples | Action | +|-------|----------|--------| +| **Retryable (transient)** | Network timeout, DNS failure, HTTP 5xx from Paperclip/GitHub, rate-limit (HTTP 429) with retry-after | Retry with exponential backoff, max 3 attempts. | +| **Terminal** | PR does not exist, issue not found, insufficient permissions (HTTP 403/401), invalid request body (HTTP 400) | Stop, post a blocker comment, leave issue in non-done state. | +| **Already-complete / idempotent** | Comment already posted, duplicate evidence already recorded | Skip as success, no retry. | + +## 4. Retry schedule + +| Attempt | Backoff | Evidence recorded | +|---------|---------|-------------------| +| 1 (initial) | immediate | raw error + context | +| 2 | 30 s | raw error + context | +| 3 (final) | 60 s | raw error + context | + +After the third failure the failure is treated as terminal. + +## 5. Comment artifact format + +Every retry and terminal outcome must produce an issue comment containing: + +- `step`: the workflow step that failed (e.g., `post_pr_comment`). +- `attempt`: current attempt number / max attempts. +- `failure_class`: `retryable` or `terminal`. +- `error`: concise error text or HTTP status + body excerpt. +- `next_action`: what the agent will do next (retry, stop-and-block, skip). + +### Example retry comment + +```text +[pr-workflow-comment] Retryable failure on step `post_pr_comment` (attempt 1/3). +- Error: HTTP 504 Gateway Timeout from Paperclip API. +- Next action: wait 30 s and retry. +``` + +### Example terminal comment + +```text +[pr-workflow-comment] Terminal failure on step `post_pr_comment` (attempt 3/3). +- Error: HTTP 404 Issue not found. +- Next action: stop; issue left in blocked state pending manual review. +``` + +## 6. Exit gates + +Before transitioning the parent PR workflow issue to `done`: + +1. The PR comment step must either succeed, be idempotently skipped, or fail terminally with a blocker comment. +2. A terminal failure must **not** clear the issue to `done`; the issue must remain `blocked` or `in_progress`. +3. Every retry and terminal outcome must be visible in the issue comments. + +## 7. Related issues + +- YAS-46: E2E TEST 2 — Add LMS PR workflow comment to README +- YAS-64: Decompose PR workflow comment task into verifiable steps +- YAS-78: Split PR workflow comment task into discrete steps +- YAS-81: Add per-step evidence to PR workflow comment bodies