@yemi33/minions 0.1.2156 → 0.1.2158

package/dashboard/js/render-work-items.js

@@ -885,8 +885,26 @@ function viewAgentOutput(logPath) {
 function openInboxNote(filename) {
   var idx = (inboxData || []).findIndex(function(item) { return item.name === filename; });
   if (idx >= 0) { openModal(idx); return; }
-  closeModal();
-  switchPage('inbox');
+  // Not in the live inbox — it's an archived note (the common case for a
+  // completed work item's note pill, which the rewriter re-encodes as an
+  // 'archive:<name>' token). Fetch it from notes/archive/ and show it in the
+  // modal instead of bouncing to the inbox page. Falls back to the inbox page
+  // only if the file is genuinely gone (e.g. merged into notes.md).
+  fetch('/state/notes/archive/' + encodeURIComponent(filename))
+    .then(function(r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.text(); })
+    .then(function(content) {
+      var titleEl = document.getElementById('modal-title');
+      var bodyEl = document.getElementById('modal-body');
+      if (!titleEl || !bodyEl) return;
+      titleEl.textContent = filename + ' (archived)';
+      // eslint-disable-next-line no-unsanitized/property -- reason: renderMd() escapes note content before assembling HTML; filename is set via textContent
+      bodyEl.innerHTML = '<div style="font-size:var(--text-md);line-height:1.7;color:var(--muted)">' + renderMd(content) + '</div>';
+      document.getElementById('modal').classList.add('open');
+    })
+    .catch(function() {
+      closeModal();
+      switchPage('inbox');
+    });
 }
 
 if (typeof window !== 'undefined') {

package/docs/completion-reports.md

@@ -86,6 +86,7 @@ Do **not** invent, regenerate, or share the nonce across dispatches — each spa
 | `followups` | array | Optional. PR-comment follow-up work items the agent dispatched via `POST /api/work-items` with `meta.pr_followup` set. Each entry: `{wi_id, title, reason, parent_comment_id}`. See [PR-comment follow-ups](#pr-comment-follow-ups). |
 | `meta.review` | object | Optional, review tasks only. Records project-local review-skill outcome — see [Review skill outcomes](#review-skill-outcomes). Aliased by the generalized `meta.skill` (W-mq1cczi90006b21f). |
 | `meta.skill` | object | Optional. Records project-local skill outcome for ANY playbook type that surfaces a `## Project skills` block (implement / fix / plan / review / etc.). See [Project skill outcomes](#project-skill-outcomes). |
+| `meta.descriptionAudit` | object | Optional, `fix` / `implement` dispatches that push commits. Records the PR description audit + screenshot-refresh outcome — see [PR description audit](#pr-description-audit). |
 
 ## Project skill outcomes
 
@@ -150,6 +151,44 @@ All `meta.review` fields are optional and backward-compatible — older agents t
 
 Dispatchers can suppress the block entirely by setting `meta.skipProjectReviewSkills: true` on the review work item — the playbook then renders identically to the pre-W-mq16xtdx 8-step contract. Use this for meta-reviews of the review skill itself; the engine still accepts `meta.review.skillSkipped` in the report regardless. (W-mq1cczi90006b21f generalized this to `meta.skipProjectSkills`, which suppresses the block on every dispatch type — both flags are honored.)
 
+## PR description audit
+
+W-mq5l3f2u000i9045. The `fix` and `implement` playbooks inline a `## PR description audit` section that the agent runs **after** pushing commits to the PR's source branch and **before** marking the work item done. The audit re-reads the PR description, compares it against the diff of the newly-pushed commits, and patches stale sections (feature lists, config tables, file/line counts, ASCII diagrams, embedded screenshots) so reviewers don't end up reading outdated prose.
+
+The audit is best-effort:
+
+- Screenshot recapture requires a runnable dev server (detected via `package.json` scripts named `dev`, `start`, or `serve`) and Playwright MCP. When either is missing or fails, the agent skips the recapture without failing the work item.
+- GitHub does not expose a documented REST endpoint for PR-comment image uploads; the agent skips the recapture on GitHub with `result: "screenshots-refreshed-skipped (gh-attachment-unavailable)"` instead of failing.
+- Raw PNGs are saved under `agents/<id>/screenshots/` only. **Screenshots NEVER land in the repo** — adding any code path that `git add`s a PNG is a release-blocker bug.
+- The audit never introduces screenshots to a PR that didn't already have any (refresh only), never modifies the PR title, never toggles draft state, and never posts a separate PR comment narrating the description change.
+
+Record the outcome under `meta.descriptionAudit`. All fields are optional and backward-compatible — older agents that never set them stay valid.
+
+```json
+{
+  "status": "success",
+  "meta": {
+    "descriptionAudit": {
+      "ran": true,
+      "result": "description-patched",
+      "oldScreenshots": [],
+      "newScreenshots": [],
+      "patchedSections": ["feature-bullets", "config-table"]
+    }
+  }
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `meta.descriptionAudit.ran` | boolean | `true` if the agent executed the audit (whether or not it edited the description). `false` when the audit was suppressed (no commits pushed, no-op completion, `meta.skipDescriptionAudit` set, or the playbook skipped the audit for any reason). Omit `meta.descriptionAudit` entirely when the audit was not even considered. |
+| `meta.descriptionAudit.result` | string | One of: `"no-changes-needed"`, `"description-patched"`, `"screenshots-refreshed"`, `"description-patched+screenshots-refreshed"`, or `"skipped:<reason>"` (e.g. `"skipped:meta-flag"`, `"skipped:no-commits"`, `"skipped:noop"`). The `"screenshots-refreshed-skipped (gh-attachment-unavailable)"` shape is also valid when GitHub's attachment limitation forces a partial-skip. |
+| `meta.descriptionAudit.oldScreenshots` | string[] | URLs of image refs the agent replaced. Omit or `[]` when no screenshots changed. |
+| `meta.descriptionAudit.newScreenshots` | string[] | URLs of newly uploaded image attachments. Omit or `[]` when no screenshots changed. |
+| `meta.descriptionAudit.patchedSections` | string[] | Human-readable identifiers of the description sections that changed (e.g. `"feature-bullets"`, `"config-table"`, `"file-list"`, `"line-counts"`, `"ascii-diagram"`, `"screenshots"`). Omit or `[]` when no sections changed. |
+
+Dispatchers can suppress the audit entirely by setting `meta.skipDescriptionAudit: true` on the work item — the playbook then renders an explicit "audit suppressed" notice instead of the audit steps. Use this for skill-meta updates, doc-only fixes whose PR description text won't be affected by the diff, and follow-up dispatches that explicitly own the description themselves.
+
 ## `failure_class` enum
 
 Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated string.

package/engine/playbook.js

@@ -307,6 +307,14 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   // projects legitimately resolve it to ''.
   'project_review_skills_block',
   'skip_project_review_skills',
+  // W-mq5l3f2u000i9045 — opt-out flag for the PR description audit + screenshot
+  // refresh fragment inlined into fix.md / implement.md. Truthy (set when
+  // item.meta.skipDescriptionAudit is true) renders the "audit suppressed"
+  // notice; falsy/empty leaves the notice block out and the agent runs the
+  // standard audit. Optional because (a) every other playbook ignores the var
+  // and (b) the default state is the empty string, which the playbook's
+  // conditional block treats as "not skipped".
+  'skip_description_audit',
   // P-e6b3c2d8 — QA Session template vars. session_id / target_kind /
   // flows_raw / managed_spawn_name are required (declared in
   // PLAYBOOK_REQUIRED_VARS['qa-session-setup']); these target_* sub-fields
@@ -435,7 +443,12 @@ function isSafePlaybookType(playbookType) {
     !name.includes('..') &&
     !/[\\/]/.test(name) &&
     !path.isAbsolute(name) &&
-    !/^[a-zA-Z]:/.test(name);
+    !/^[a-zA-Z]:/.test(name) &&
+    // W-mq5l3f2u000i9045 — files named `_*.md` are shared fragments inlined
+    // into dispatching playbooks (e.g. `_pr-description-audit.md`). They are
+    // not standalone playbooks; reject `_…` types so a dispatch can never
+    // resolve to a fragment file.
+    !name.startsWith('_');
 }
 
 function resolvePlaybookPath(projectName, playbookType) {
@@ -1171,7 +1184,14 @@ function buildPrDispatch(agentId, config, project, pr, type, extraVars, taskLabe
     // (skipProjectReviewSkills is the PR-82 alias). Default OFF: review/fix
     // dispatches surface the project-local skills block.
     skip_project_review_skills: !!(meta && meta.skipProjectReviewSkills),
+    // W-mq1cczi90006b21f — generalized project-skills suppression flag.
+    // Honors either the new `meta.skipProjectSkills` or the PR-82
+    // `meta.skipProjectReviewSkills` alias so older work items keep working.
     skip_project_skills: !!(meta && (meta.skipProjectSkills || meta.skipProjectReviewSkills)),
+    // W-mq5l3f2u000i9045 — opt-out for the inlined PR description audit
+    // section in fix.md. Truthy renders the "audit suppressed" notice; falsy
+    // (the default) leaves the standard audit instructions in place.
+    skip_description_audit: !!(meta && meta.skipDescriptionAudit),
     ...extraVars,
     task_id: dispatchId,
   };

package/engine.js

@@ -6121,6 +6121,14 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     managed_spawn_ttl_minutes: item.meta && Number.isFinite(Number(item.meta.managed_spawn_ttl_minutes))
       ? Math.floor(Number(item.meta.managed_spawn_ttl_minutes))
       : '',
+    // W-mq5l3f2u000i9045 — opt-out flag for the inlined PR description audit
+    // section in fix.md / implement.md. When the dispatcher sets
+    // item.meta.skipDescriptionAudit (skill-meta updates, doc-only fixes,
+    // follow-up dispatches that explicitly own the description), the playbook
+    // renders the "audit suppressed" notice instead of the standard audit
+    // steps. Default off — every fix/implement dispatch that pushes commits
+    // audits the PR description by default.
+    skip_description_audit: !!(item.meta && item.meta.skipDescriptionAudit),
     // W-mpeiwz6k0005bf34-c — opt-in qa-validate context. The dispatch handler
     // POST /api/qa/runbooks/run stamps meta.qaRunId + meta.qaRunbook (full
     // spec) + meta.qaTarget (managed-process snapshot) on the work item;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2156",
+  "version": "0.1.2158",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/playbooks/_pr-description-audit.md

@@ -0,0 +1,142 @@
+# PR description audit + screenshot refresh (shared fragment)
+
+> **Naming convention.** Files named `_*.md` under `playbooks/` are **shared
+> fragments**. The engine renderer (`engine/playbook.js`) does not (yet)
+> implement an `<include>` directive, so each consuming playbook inlines this
+> fragment verbatim and the two copies are kept in sync by hand. If you change
+> this file, also update the inlined copies in `playbooks/fix.md` and
+> `playbooks/implement.md` (and any other playbook that pushes commits to a
+> tracked PR). The matching test in `test/unit/config-and-playbooks.test.js`
+> ("PR description audit fragment is inlined consistently") fails fast when the
+> copies drift.
+
+## When to run
+
+Run this audit **after** you push new commits to the PR's source branch and
+**before** you mark the work item done.
+
+Skip the audit entirely when:
+
+- This dispatch was invoked with `meta.skipDescriptionAudit: true` (the
+  engine renders an explicit "audit suppressed" notice when the flag is set).
+- You did not push any new commits this dispatch (no behavior change → no
+  description drift).
+- The dispatch produced a no-op completion (`noop: true`).
+
+When you skip, still report it: set `meta.descriptionAudit.ran = false` and
+`meta.descriptionAudit.result = "skipped:<reason>"` in the completion JSON.
+
+## Audit steps
+
+1. **Fetch the current PR description.**
+   - GitHub: `gh pr view <num> --repo <owner>/<repo> --json body --jq .body`
+   - Azure DevOps: `az repos pr show --id <num> --query description -o tsv`
+2. **Compute the diff for the commits you just pushed.**
+   - `git log --stat <baseline>..HEAD` where `<baseline>` is `origin/main` for
+     the first push or `origin/<branch>@{1}` (pre-push tip) for follow-up
+     pushes. `git log --oneline <baseline>..HEAD` if you only need the SHA list.
+3. **Compare description sections against the diff.** For each section,
+   evaluate whether the new commits change anything it claims. Focus
+   specifically on:
+   - Feature lists / "what changed" bullet points
+   - Config / option / matrix tables
+   - File or path lists
+   - Line counts, before/after metrics, perf numbers, table cell values
+   - ASCII diagrams that depict layout the diff touched
+   - Embedded markdown image refs (`![alt](url)`) — see the screenshot
+     subsection below
+4. **Decide the result.**
+   - Description is consistent with the diff → no-op. Record
+     `meta.descriptionAudit = { ran: true, result: "no-changes-needed" }`
+     in the completion report and stop here.
+   - Description needs targeted edits → build the patched body. **Preserve prose voice**. Edit only the stale parts. Do **not** rewrite. Do **not**
+     add new sections that weren't there before. Do **not** change the PR
+     title. Do **not** flip draft state, close/reopen, or post a separate PR
+     comment narrating the description edit.
+5. **Push the patched description.**
+   - GitHub: write the new body to a temp file, then
+     `gh pr edit <num> --repo <owner>/<repo> --body-file <file>`
+   - Azure DevOps:
+     `az repos pr update --id <num> --description "$(Get-Content -Raw <file>)"`
+     (PowerShell) or the POSIX equivalent. ADO's description field also
+     truncates around ~4 KB on the `--description` flag — if you hit that,
+     fall back to `az rest --method patch` against
+     `…/pullRequests/<id>?api-version=7.1` with `{ "description": "<body>" }`.
+6. **GET-verify the description post-patch** by re-running the fetch from
+   step 1 and confirming the body matches what you sent.
+
+## Screenshot handling
+
+This applies only when the **existing** description embeds markdown image
+refs. **Never introduce screenshots to a PR that didn't already have any** —
+this audit is a refresh, not an introduction.
+
+1. Extract every `![alt](url)` from the current description.
+2. For each image, decide whether it depicts a view this dispatch's diff
+   touched. Heuristics (any one is enough):
+   - `alt` text or filename mentions a component / route / view name that
+     appears in the changed files.
+   - The image URL path contains an issue/PR id matching this PR.
+   - The description text immediately around the image references files
+     present in the diff.
+3. If the view was touched **and** the project has a runnable dev server
+   (detect via `package.json` scripts named `dev`, `start`, or `serve`)
+   **and** Playwright MCP is available, recapture:
+   1. Spin up the dev server with a detached handoff (see
+      `shared-rules.md` → "Long-Running Commands"). Capture PID + log path +
+      URL + stop command.
+   2. Drive Playwright MCP to the relevant route and screenshot the same
+      view. Save raw PNGs to `agents/<id>/screenshots/` only. **NEVER `git add` a PNG** — adding any code path that commits a screenshot is a
+      release-blocker bug.
+   3. Upload as a PR attachment:
+      - **ADO**: `PUT /pullRequests/<id>/attachments/<filename>` with the
+        PNG bytes, then reference the returned URL in the description.
+      - **GitHub**: there is no documented REST endpoint for PR-comment
+        image uploads. The browser drag-drop path uses
+        `github.com/upload/asset`, which `gh` does not wrap. If you cannot
+        find a reliable scripted upload path, **skip** this screenshot,
+        leave the old image URL in place, and record
+        `meta.descriptionAudit.result = "screenshots-refreshed-skipped (gh-attachment-unavailable)"`.
+   4. Patch the description to swap old image URLs for new.
+   5. Stop the dev server using the recorded stop command.
+4. If the dev server fails to start, the route 404s, Playwright fails, or
+   the host's attachment API is unreachable → **skip that screenshot**
+   without failing the work item. Record the skip and the reason in
+   `meta.descriptionAudit`.
+
+## Out-of-scope guardrails
+
+- Don't add screenshots that weren't already there.
+- Don't rewrite description prose beyond the targeted stale edits.
+- Don't modify the PR title.
+- Don't toggle draft state, close/reopen the PR, or post a separate PR
+  comment narrating the description change.
+- Don't fail the work item on a screenshot or attachment failure — degrade
+  gracefully and record the skip.
+- Screenshots **never** land in the repo. Save raw PNGs only under
+  `agents/<id>/screenshots/`. No `git add` of any PNG, ever.
+
+## Completion-report shape
+
+When the audit ran (whether it edited the description or no-op'd), include
+this block in the JSON completion report (see
+`docs/completion-reports.md` → "PR description audit"):
+
+```json
+{
+  "meta": {
+    "descriptionAudit": {
+      "ran": true,
+      "result": "description-patched",
+      "oldScreenshots": [],
+      "newScreenshots": [],
+      "patchedSections": ["feature-bullets", "config-table"]
+    }
+  }
+}
+```
+
+Omit `meta.descriptionAudit` entirely when the audit did not run (no
+commits pushed, no-op completion, etc.). When `meta.skipDescriptionAudit`
+suppressed the audit, set `ran: false` and
+`result: "skipped:meta-flag"` so the audit history stays auditable.

package/playbooks/fix.md

@@ -99,6 +99,77 @@ Do NOT remove the worktree — the engine handles cleanup automatically.
 - content: Explain what was fixed, reference each review finding, include build/test status
 - Sign: `Fixed by Minions ({{agent_name}} — {{agent_role}} · {{agent_model}})`
 
+## PR description audit (mandatory unless `meta.skipDescriptionAudit`)
+
+<!-- Inlined from playbooks/_pr-description-audit.md — keep in sync (enforced by test/unit/config-and-playbooks.test.js). -->
+
+{{#skip_description_audit}}
+> **Audit suppressed.** This dispatch was invoked with `meta.skipDescriptionAudit: true`.
+> Record `meta.descriptionAudit = { ran: false, result: "skipped:meta-flag" }` in your completion report
+> and skip the audit steps below entirely.
+{{/skip_description_audit}}
+
+After you push commits to the PR's source branch and BEFORE you mark the work item done, audit the PR description and refresh it to match the new diff. Skip the audit when you pushed no commits this dispatch or when the dispatch is a no-op completion; record the skip in `meta.descriptionAudit`.
+
+**Audit steps**
+
+1. Fetch the current PR description.
+   - GitHub: `gh pr view <num> --repo <owner>/<repo> --json body --jq .body`
+   - Azure DevOps: `az repos pr show --id <num> --query description -o tsv`
+2. Compute the diff for the commits you just pushed: `git log --stat <baseline>..HEAD` where `<baseline>` is `origin/<branch>@{1}` for follow-up pushes (or `origin/main` for the very first push).
+3. For each section of the description, evaluate whether the new diff invalidates anything it claims. Focus on: feature lists / "what changed" bullets, config/option tables, file or path lists, line counts, before/after metrics, ASCII diagrams, and embedded markdown image refs.
+4. **No drift** → record `meta.descriptionAudit = { ran: true, result: "no-changes-needed" }` and stop.
+5. **Drift detected** → build a patched body. **Preserve prose voice.** Edit only the stale parts. Do NOT rewrite. Do NOT add new sections. Do NOT change the PR title. Do NOT toggle draft state. Do NOT post a separate PR comment narrating the description change.
+6. Push the patched description.
+   - GitHub: write the new body to a temp file, then `gh pr edit <num> --repo <owner>/<repo> --body-file <file>`.
+   - Azure DevOps: `az repos pr update --id <num> --description "$(Get-Content -Raw <file>)"`. If the body exceeds ~4 KB, fall back to `az rest --method patch` against `…/pullRequests/<id>?api-version=7.1` with `{ "description": "<body>" }`.
+7. GET-verify the description post-patch by re-running step 1 and confirming the body matches what you sent.
+
+**Screenshot handling (refresh-only — never introduce screenshots)**
+
+This applies only when the **existing** description embeds markdown image refs (`![alt](url)`). NEVER add screenshots to a PR that didn't already have any.
+
+1. Extract every `![alt](url)` from the current description.
+2. Decide which images depict views this dispatch's diff touched (heuristic: alt text / filename / surrounding prose mentions a component / route / view name present in the changed files).
+3. If the view was touched AND the project has a runnable dev server (detect via `package.json` scripts named `dev`, `start`, or `serve`) AND Playwright MCP is available, recapture:
+   - Spin up the dev server with a detached handoff per `shared-rules.md` → "Long-Running Commands". Record PID + log path + URL + stop command.
+   - Drive Playwright MCP to the relevant route and screenshot the view. Save raw PNGs to `agents/<id>/screenshots/` ONLY. **NEVER `git add` a PNG** — committing a screenshot is a release-blocker bug.
+   - Upload as a PR attachment:
+     - **ADO**: `PUT /pullRequests/<id>/attachments/<filename>` with the PNG bytes, then reference the returned URL in the description.
+     - **GitHub**: no documented REST endpoint exists for PR-comment image uploads (the browser drag-drop uses `github.com/upload/asset`, which `gh` does not wrap). If you cannot find a reliable scripted upload path, **skip** the recapture, leave the old image URL in place, and record `meta.descriptionAudit.result = "screenshots-refreshed-skipped (gh-attachment-unavailable)"`.
+   - Patch the description to swap old image URLs for new.
+   - Stop the dev server using the recorded stop command.
+4. If the dev server fails to start, the route 404s, Playwright fails, or the host's attachment API is unreachable → **skip that screenshot** without failing the work item. Record the skip and the reason in `meta.descriptionAudit`.
+
+**Out-of-scope guardrails**
+
+- Don't add screenshots that weren't already there. Refresh only.
+- Don't rewrite description prose beyond the targeted stale edits.
+- Don't modify the PR title; don't toggle draft state, close/reopen the PR.
+- Don't post a separate PR comment summarizing the description change.
+- Don't fail the work item on a screenshot or attachment failure — degrade gracefully and record the skip.
+- Screenshots NEVER land in the repo. `agents/<id>/screenshots/` only; never `git add` a PNG.
+
+**Completion-report shape**
+
+When the audit ran (whether it edited the description or no-op'd), include this in the completion JSON (full schema: `docs/completion-reports.md` → "PR description audit"):
+
+```json
+{
+  "meta": {
+    "descriptionAudit": {
+      "ran": true,
+      "result": "description-patched",
+      "oldScreenshots": [],
+      "newScreenshots": [],
+      "patchedSections": ["feature-bullets", "config-table"]
+    }
+  }
+}
+```
+
+Omit `meta.descriptionAudit` entirely when the audit did not run (no commits pushed, no-op completion). When `meta.skipDescriptionAudit` suppressed the audit, set `ran: false` and `result: "skipped:meta-flag"`.
+
 ## Resolve Review Comments
 
 After pushing, respond to each review comment/thread. **Every disposition requires a reply before you resolve, close, or mark-fixed the thread — no exceptions.** Resolving a thread silently is a process violation (see "Resolving Review Threads — No Silent Closures" in `shared-rules.md`).

package/playbooks/implement.md

@@ -101,6 +101,77 @@ Create the PR for implement tasks — the engine tracks review and completion fr
 
 Include build/test status and run instructions in the PR description. If the project has a runnable app, include the localhost URL.
 
+## PR description audit (mandatory unless `meta.skipDescriptionAudit`)
+
+<!-- Inlined from playbooks/_pr-description-audit.md — keep in sync (enforced by test/unit/config-and-playbooks.test.js). -->
+
+{{#skip_description_audit}}
+> **Audit suppressed.** This dispatch was invoked with `meta.skipDescriptionAudit: true`.
+> Record `meta.descriptionAudit = { ran: false, result: "skipped:meta-flag" }` in your completion report
+> and skip the audit steps below entirely.
+{{/skip_description_audit}}
+
+After you push commits to the PR's source branch and BEFORE you mark the work item done, audit the PR description and refresh it to match the new diff. Skip the audit when you pushed no commits this dispatch or when the dispatch is a no-op completion; record the skip in `meta.descriptionAudit`.
+
+**Audit steps**
+
+1. Fetch the current PR description.
+   - GitHub: `gh pr view <num> --repo <owner>/<repo> --json body --jq .body`
+   - Azure DevOps: `az repos pr show --id <num> --query description -o tsv`
+2. Compute the diff for the commits you just pushed: `git log --stat <baseline>..HEAD` where `<baseline>` is `origin/<branch>@{1}` for follow-up pushes (or `origin/main` for the very first push).
+3. For each section of the description, evaluate whether the new diff invalidates anything it claims. Focus on: feature lists / "what changed" bullets, config/option tables, file or path lists, line counts, before/after metrics, ASCII diagrams, and embedded markdown image refs.
+4. **No drift** → record `meta.descriptionAudit = { ran: true, result: "no-changes-needed" }` and stop.
+5. **Drift detected** → build a patched body. **Preserve prose voice.** Edit only the stale parts. Do NOT rewrite. Do NOT add new sections. Do NOT change the PR title. Do NOT toggle draft state. Do NOT post a separate PR comment narrating the description change.
+6. Push the patched description.
+   - GitHub: write the new body to a temp file, then `gh pr edit <num> --repo <owner>/<repo> --body-file <file>`.
+   - Azure DevOps: `az repos pr update --id <num> --description "$(Get-Content -Raw <file>)"`. If the body exceeds ~4 KB, fall back to `az rest --method patch` against `…/pullRequests/<id>?api-version=7.1` with `{ "description": "<body>" }`.
+7. GET-verify the description post-patch by re-running step 1 and confirming the body matches what you sent.
+
+**Screenshot handling (refresh-only — never introduce screenshots)**
+
+This applies only when the **existing** description embeds markdown image refs (`![alt](url)`). NEVER add screenshots to a PR that didn't already have any.
+
+1. Extract every `![alt](url)` from the current description.
+2. Decide which images depict views this dispatch's diff touched (heuristic: alt text / filename / surrounding prose mentions a component / route / view name present in the changed files).
+3. If the view was touched AND the project has a runnable dev server (detect via `package.json` scripts named `dev`, `start`, or `serve`) AND Playwright MCP is available, recapture:
+   - Spin up the dev server with a detached handoff per `shared-rules.md` → "Long-Running Commands". Record PID + log path + URL + stop command.
+   - Drive Playwright MCP to the relevant route and screenshot the view. Save raw PNGs to `agents/<id>/screenshots/` ONLY. **NEVER `git add` a PNG** — committing a screenshot is a release-blocker bug.
+   - Upload as a PR attachment:
+     - **ADO**: `PUT /pullRequests/<id>/attachments/<filename>` with the PNG bytes, then reference the returned URL in the description.
+     - **GitHub**: no documented REST endpoint exists for PR-comment image uploads (the browser drag-drop uses `github.com/upload/asset`, which `gh` does not wrap). If you cannot find a reliable scripted upload path, **skip** the recapture, leave the old image URL in place, and record `meta.descriptionAudit.result = "screenshots-refreshed-skipped (gh-attachment-unavailable)"`.
+   - Patch the description to swap old image URLs for new.
+   - Stop the dev server using the recorded stop command.
+4. If the dev server fails to start, the route 404s, Playwright fails, or the host's attachment API is unreachable → **skip that screenshot** without failing the work item. Record the skip and the reason in `meta.descriptionAudit`.
+
+**Out-of-scope guardrails**
+
+- Don't add screenshots that weren't already there. Refresh only.
+- Don't rewrite description prose beyond the targeted stale edits.
+- Don't modify the PR title; don't toggle draft state, close/reopen the PR.
+- Don't post a separate PR comment summarizing the description change.
+- Don't fail the work item on a screenshot or attachment failure — degrade gracefully and record the skip.
+- Screenshots NEVER land in the repo. `agents/<id>/screenshots/` only; never `git add` a PNG.
+
+**Completion-report shape**
+
+When the audit ran (whether it edited the description or no-op'd), include this in the completion JSON (full schema: `docs/completion-reports.md` → "PR description audit"):
+
+```json
+{
+  "meta": {
+    "descriptionAudit": {
+      "ran": true,
+      "result": "description-patched",
+      "oldScreenshots": [],
+      "newScreenshots": [],
+      "patchedSections": ["feature-bullets", "config-table"]
+    }
+  }
+}
+```
+
+Omit `meta.descriptionAudit` entirely when the audit did not run (no commits pushed, no-op completion). When `meta.skipDescriptionAudit` suppressed the audit, set `ran: false` and `result: "skipped:meta-flag"`.
+
 ## When to Stop
 
 Your task is complete when the requested implementation is delivered, the validation story is truthful and sufficient for review, the branch is pushed, and the PR exists. Include the PR URL in your final message so the engine can track it.