YAS-251: Append second validation line to README.md

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).
+

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