@yemi33/minions 0.1.2423 → 0.1.2425

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2423",
+  "version": "0.1.2425",
   "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

@@ -65,56 +65,96 @@ When you skip, still report it: set `meta.descriptionAudit.ran = false` and
 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`.
+## Screenshot handling (introduce AND refresh for visual changes)
+
+For a PR that contains a **meaningful visual/UI change**, proactively CAPTURE
+screenshots and EMBED them directly in the PR description — do **not** rely only
+on the OPG `Visual evidence capture` CI bot (that bot stays as-is; this is
+additive PR-body evidence). When the existing description already embeds
+`![alt](url)` refs for a view this dispatch touched, refresh them the same way.
+
+**Scope guard — which changes get screenshots.** Only meaningful visual/UI
+changes: dashboard pages, slim-ux, Settings, work-item/PR/plan views, badges,
+layout/CSS. Skip backend-only, engine-logic, text/prose-only, analysis, and
+docs changes — those get NO screenshots (they add no signal). Use a BEFORE/AFTER
+pair for layout/visual FIXES; an AFTER-only shot for NEW UI.
+
+**Capture.** If the project has a runnable dev server (detect via
+`package.json` scripts named `dev`, `start`, or `serve`) AND Playwright MCP is
+available:
+
+1. Spin up the dev server with a detached handoff (see `shared-rules.md` →
+   "Long-Running Commands"). Record PID + log path + URL + stop command.
+2. Drive Playwright MCP to the changed route at a normal viewport and
+   screenshot the section that changed. Save raw PNGs to
+   `agents/<id>/screenshots/` ONLY. **NEVER `git add` a PNG** — committing a
+   screenshot is a release-blocker bug.
+3. Stop the dev server using the recorded stop command.
+
+**Upload + embed — GitHub (release-asset CDN recipe).** GitHub has no
+documented REST endpoint for PR-comment image uploads, so publish the PNGs as
+assets on a dedicated per-PR prerelease and embed the asset CDN URLs. This works
+on PRIVATE repos and never commits PNGs to the source branch. Resolve the
+correct account token for the repo owner and build a per-command `GH_TOKEN` —
+**NEVER run `gh auth switch`** (`opg-microsoft` → `yemishin_microsoft`,
+`yemi33` → `yemi33`).
+
+bash:
+
+```bash
+OWNER=opg-microsoft; REPO=minions; PR=<num>; TAG="pr-${PR}-visual"
+GH_TOKEN=$(gh auth token --user yemishin_microsoft --hostname github.com)
+# Create the per-PR prerelease once; on re-dispatch, upload --clobber instead.
+GH_TOKEN=$GH_TOKEN gh release create "$TAG" agents/<id>/screenshots/*.png \
+  --repo "$OWNER/$REPO" --title "PR #${PR} visual evidence" --prerelease \
+  --notes "Visual evidence for PR #${PR}" \
+  || GH_TOKEN=$GH_TOKEN gh release upload "$TAG" agents/<id>/screenshots/*.png \
+     --repo "$OWNER/$REPO" --clobber
+# Resolve each asset's public CDN url:
+URL=$(GH_TOKEN=$GH_TOKEN gh api "repos/$OWNER/$REPO/releases/tags/$TAG" \
+  --jq '.assets[]|select(.name=="after.png")|.browser_download_url')
+```
+
+PowerShell:
+
+```powershell
+$OWNER='opg-microsoft'; $REPO='minions'; $PR=<num>; $TAG="pr-$PR-visual"
+$env:GH_TOKEN = (gh auth token --user yemishin_microsoft --hostname github.com)
+$pngs = Get-ChildItem agents/<id>/screenshots/*.png
+gh release create $TAG $pngs --repo "$OWNER/$REPO" --title "PR #$PR visual evidence" --prerelease --notes "Visual evidence for PR #$PR"
+if ($LASTEXITCODE -ne 0) { gh release upload $TAG $pngs --repo "$OWNER/$REPO" --clobber }
+$URL = (gh api "repos/$OWNER/$REPO/releases/tags/$TAG" --jq '.assets[]|select(.name=="after.png")|.browser_download_url')
+```
+
+Then embed each asset in the PR body as `![<view> (after)](<url>)` (BEFORE/AFTER
+pair for fixes, AFTER-only for new UI) and patch the description with
+`gh pr edit <num> --repo <owner>/<repo> --body-file <file>`.
+
+**Upload + embed — Azure DevOps.** ADO exposes a scriptable attachment API:
+`PUT /pullRequests/<id>/attachments/<filename>` with the PNG bytes, then
+reference the returned URL in the description. This now applies to
+newly-introduced screenshots too, not just refreshes.
+
+**Degrade gracefully.** If the dev server won't start, the route 404s,
+Playwright is unavailable, or the upload fails → **SKIP** without failing the
+work item and record the skip + reason in `meta.descriptionAudit` (e.g.
+`result: "screenshots-skipped (dev-server-unavailable)"`). Screenshots NEVER
+land in the repo — `agents/<id>/screenshots/` only; never `git add` a PNG.
 
 ## Out-of-scope guardrails
 
-- Don't add screenshots that weren't already there.
+- Only screenshot **meaningful visual/UI changes** (see the scope guard above);
+  skip backend/engine/text/analysis/docs changes — they add no signal.
 - 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.
+- Don't fail the work item on a screenshot or upload/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.
+- Never run `gh auth switch`; build a per-command `GH_TOKEN` for the repo
+  owner's account.
 
 ## Completion-report shape
 
@@ -136,6 +176,13 @@ this block in the JSON completion report (see
 }
 ```
 
+When you **introduce** screenshots for a visual change, set
+`result: "screenshots-introduced"` (or
+`"description-patched+screenshots-introduced"` when you also patched prose),
+and list the embedded asset URLs in `newScreenshots`. Use
+`"screenshots-refreshed"` when you only swapped pre-existing image refs, and a
+`"screenshots-skipped (<reason>)"` shape when capture/upload was skipped.
+
 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

package/playbooks/build-fix-complex.md

@@ -135,12 +135,12 @@ After you push commits to the PR's source branch and BEFORE you mark the work it
 
 **Out-of-scope guardrails**
 
-- Don't add screenshots that weren't already there. Refresh only.
+- Only screenshot **meaningful visual/UI changes** (dashboard pages, slim-ux, Settings, work-item/PR/plan views, badges, layout/CSS); skip backend/engine/text/analysis/docs changes. When a build fix does touch a visual surface, proactively capture + embed via the release-asset recipe in `_pr-description-audit.md` (BEFORE/AFTER for fixes, AFTER-only for new UI).
 - 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.
+- Don't fail the work item on a screenshot or upload/attachment failure — degrade gracefully and record the skip.
+- Screenshots NEVER land in the repo. `agents/<id>/screenshots/` only; never `git add` a PNG. Never `gh auth switch` — use a per-command `GH_TOKEN`.
 
 **Completion-report shape**
 

package/playbooks/docs.md

@@ -111,8 +111,8 @@ git push -u origin {{branch_name}}
 ```
 
 Create the PR for docs tasks — docs go through the same review flow as code.
-Use the appropriate repo-host tooling for PR creation. For Azure DevOps, prefer the
-`az` CLI first and use the ADO MCP only as a fallback.
+
+{{pr_create_instructions}}
 {{/shared_branch}}
 
 ## Rules

package/playbooks/fix.md

@@ -47,13 +47,13 @@ This dispatch addresses finding `{{review_finding_id}}`. A successful review fix
 {
   "reviewFindingResolution": {
     "findingId": "{{review_finding_id}}",
-    "disposition": "already-resolved",
+    "disposition": "satisfied-elsewhere",
     "currentCodeEvidence": "path/to/file.js:123 and the specific test or behavior that proves the finding is resolved"
   }
 }
 ```
 
-`disposition` may be `already-resolved` or `invalid`. Cite a current `file:line` or commit plus the inspected behavior; shared-account ownership, `viewerDidAuthor`, or reviewer/fixer equality alone is rejected and retried without consuming the PR no-op pause budget.
+`disposition` may be `satisfied-elsewhere` or `invalid`; legacy `already-resolved` is accepted and canonicalized to `satisfied-elsewhere`. Cite a current `file:line` or commit plus the inspected behavior; shared-account ownership, `viewerDidAuthor`, or reviewer/fixer equality alone is rejected and retried without consuming the PR no-op pause budget.
 {{/review_finding_id}}
 
 For each review finding, reproduce or inspect the claimed issue before editing:
@@ -168,30 +168,30 @@ After you push commits to the PR's source branch and BEFORE you mark the work it
    - 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)**
+**Screenshot handling (introduce AND refresh for visual changes)**
 
-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.
+For a PR that contains a **meaningful visual/UI change**, proactively CAPTURE screenshots and EMBED them directly in the PR description — do NOT rely only on the OPG `Visual evidence capture` CI bot (it stays as-is; this is additive PR-body evidence). When the description already embeds `![alt](url)` refs for a view this dispatch touched, refresh them the same way.
 
-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`.
+**Scope guard — which changes get screenshots.** Only meaningful visual/UI changes: dashboard pages, slim-ux, Settings, work-item/PR/plan views, badges, layout/CSS. Skip backend-only, engine-logic, text/prose-only, analysis, and docs changes — those get NO screenshots (they add no signal). BEFORE/AFTER pair for layout/visual FIXES; AFTER-only for NEW UI.
+
+1. If the project has a runnable dev server (detect via `package.json` scripts named `dev`, `start`, or `serve`) AND Playwright MCP is available, spin it up with a detached handoff per `shared-rules.md` → "Long-Running Commands" (record PID + log path + URL + stop command).
+2. Drive Playwright MCP to the changed route at a normal viewport and screenshot the section that changed. Save raw PNGs to `agents/<id>/screenshots/` ONLY. **NEVER `git add` a PNG** — committing a screenshot is a release-blocker bug. Stop the dev server with the recorded stop command when done.
+3. Upload + embed:
+   - **GitHub (release-asset CDN recipe):** publish the PNGs as assets on a per-PR prerelease and embed the asset CDN URLs (works on PRIVATE repos, never commits PNGs). Build a per-command `GH_TOKEN` for the repo owner's account (`opg-microsoft` → `yemishin_microsoft`, `yemi33` → `yemi33`); **NEVER run `gh auth switch`**.
+     - bash: `GH_TOKEN=$(gh auth token --user yemishin_microsoft --hostname github.com)` then `GH_TOKEN=$GH_TOKEN gh release create "pr-${PR}-visual" agents/<id>/screenshots/*.png --repo <owner>/<repo> --title "PR #${PR} visual evidence" --prerelease --notes "..."` (on re-dispatch use `gh release upload "pr-${PR}-visual" … --clobber`). Resolve URLs via `gh api repos/<owner>/<repo>/releases/tags/pr-${PR}-visual --jq '.assets[]|select(.name=="after.png")|.browser_download_url'`.
+     - PowerShell: `$env:GH_TOKEN = (gh auth token --user yemishin_microsoft --hostname github.com); $pngs = Get-ChildItem agents/<id>/screenshots/*.png; gh release create "pr-$PR-visual" $pngs --repo <owner>/<repo> --title "PR #$PR visual evidence" --prerelease --notes "..."; if ($LASTEXITCODE -ne 0) { gh release upload "pr-$PR-visual" $pngs --repo <owner>/<repo> --clobber }` then `gh api ... --jq '...browser_download_url'`.
+     - Embed as `![<view> (after)](<url>)` and patch the body with `gh pr edit <num> --repo <owner>/<repo> --body-file <file>`.
+   - **ADO:** `PUT /pullRequests/<id>/attachments/<filename>` with the PNG bytes, then reference the returned URL in the description (now for newly-introduced screenshots too).
+4. Degrade gracefully: if the dev server won't start, the route 404s, Playwright is unavailable, or the upload fails → SKIP without failing the work item and record the skip + reason in `meta.descriptionAudit` (e.g. `result: "screenshots-skipped (dev-server-unavailable)"`).
 
 **Out-of-scope guardrails**
 
-- Don't add screenshots that weren't already there. Refresh only.
+- Only screenshot meaningful visual/UI changes (see scope guard); skip backend/engine/text/analysis/docs changes.
 - 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.
+- Don't fail the work item on a screenshot or upload/attachment failure — degrade gracefully and record the skip.
+- Screenshots NEVER land in the repo. `agents/<id>/screenshots/` only; never `git add` a PNG. Never `gh auth switch` — use a per-command `GH_TOKEN`.
 
 **Completion-report shape**
 

package/playbooks/implement.md

@@ -140,30 +140,30 @@ After you push commits to the PR's source branch and BEFORE you mark the work it
    - 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`.
+**Screenshot handling (introduce AND refresh for visual changes)**
+
+For a PR that contains a **meaningful visual/UI change**, proactively CAPTURE screenshots and EMBED them directly in the PR description — do NOT rely only on the OPG `Visual evidence capture` CI bot (it stays as-is; this is additive PR-body evidence). When the description already embeds `![alt](url)` refs for a view this dispatch touched, refresh them the same way.
+
+**Scope guard — which changes get screenshots.** Only meaningful visual/UI changes: dashboard pages, slim-ux, Settings, work-item/PR/plan views, badges, layout/CSS. Skip backend-only, engine-logic, text/prose-only, analysis, and docs changes — those get NO screenshots (they add no signal). BEFORE/AFTER pair for layout/visual FIXES; AFTER-only for NEW UI.
+
+1. If the project has a runnable dev server (detect via `package.json` scripts named `dev`, `start`, or `serve`) AND Playwright MCP is available, spin it up with a detached handoff per `shared-rules.md` → "Long-Running Commands" (record PID + log path + URL + stop command).
+2. Drive Playwright MCP to the changed route at a normal viewport and screenshot the section that changed. Save raw PNGs to `agents/<id>/screenshots/` ONLY. **NEVER `git add` a PNG** — committing a screenshot is a release-blocker bug. Stop the dev server with the recorded stop command when done.
+3. Upload + embed:
+   - **GitHub (release-asset CDN recipe):** publish the PNGs as assets on a per-PR prerelease and embed the asset CDN URLs (works on PRIVATE repos, never commits PNGs). Build a per-command `GH_TOKEN` for the repo owner's account (`opg-microsoft` → `yemishin_microsoft`, `yemi33` → `yemi33`); **NEVER run `gh auth switch`**.
+     - bash: `GH_TOKEN=$(gh auth token --user yemishin_microsoft --hostname github.com)` then `GH_TOKEN=$GH_TOKEN gh release create "pr-${PR}-visual" agents/<id>/screenshots/*.png --repo <owner>/<repo> --title "PR #${PR} visual evidence" --prerelease --notes "..."` (on re-dispatch use `gh release upload "pr-${PR}-visual" … --clobber`). Resolve URLs via `gh api repos/<owner>/<repo>/releases/tags/pr-${PR}-visual --jq '.assets[]|select(.name=="after.png")|.browser_download_url'`.
+     - PowerShell: `$env:GH_TOKEN = (gh auth token --user yemishin_microsoft --hostname github.com); $pngs = Get-ChildItem agents/<id>/screenshots/*.png; gh release create "pr-$PR-visual" $pngs --repo <owner>/<repo> --title "PR #$PR visual evidence" --prerelease --notes "..."; if ($LASTEXITCODE -ne 0) { gh release upload "pr-$PR-visual" $pngs --repo <owner>/<repo> --clobber }` then `gh api ... --jq '...browser_download_url'`.
+     - Embed as `![<view> (after)](<url>)` and patch the body with `gh pr edit <num> --repo <owner>/<repo> --body-file <file>`.
+   - **ADO:** `PUT /pullRequests/<id>/attachments/<filename>` with the PNG bytes, then reference the returned URL in the description (now for newly-introduced screenshots too).
+4. Degrade gracefully: if the dev server won't start, the route 404s, Playwright is unavailable, or the upload fails → SKIP without failing the work item and record the skip + reason in `meta.descriptionAudit` (e.g. `result: "screenshots-skipped (dev-server-unavailable)"`).
 
 **Out-of-scope guardrails**
 
-- Don't add screenshots that weren't already there. Refresh only.
+- Only screenshot meaningful visual/UI changes (see scope guard); skip backend/engine/text/analysis/docs changes.
 - 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.
+- Don't fail the work item on a screenshot or upload/attachment failure — degrade gracefully and record the skip.
+- Screenshots NEVER land in the repo. `agents/<id>/screenshots/` only; never `git add` a PNG. Never `gh auth switch` — use a per-command `GH_TOKEN`.
 
 **Completion-report shape**
 

package/playbooks/qa-session-draft.md

@@ -29,8 +29,9 @@ natural-language flows into a runner-native test file.
 - **Capture:** `{{capture}}`
 - **Mode:** `{{session_mode}}`
 - **Managed-spawn target:** `{{managed_spawn_name}}` (live — query
-  `http://localhost:7331/api/managed-processes/by-name?name={{managed_spawn_name}}`
+  `{{managed_spawn_lookup_url}}`
   for the freshest port / base URL / health).
+- **Test output directory (absolute):** `{{qa_test_dir}}`
 
 {{additional_context}}
 
@@ -41,8 +42,8 @@ engine dispatches for each QA Session (SETUP → DRAFT → EXECUTE). The SETUP
 agent already produced a managed-spawn sidecar and the engine spawned the
 dev-up command; the EXECUTE agent will run your drafted test against that
 live spawn. Your only deliverable is the **test file itself**, written in
-the runner's native format under
-`engine/qa-tests/{{session_id}}/` (relative to the Minions root).
+the runner's native format under the injected absolute Minions-owned
+directory `{{qa_test_dir}}`.
 
 The engine resolved a concrete **runner adapter** for this session
 (Playwright, Maestro, or a project plugin) and its `generateBrief()` hook
@@ -60,7 +61,7 @@ runner brief below, then implement exactly the file it describes.
 ### Reporting the test file path
 
 When you exit, your completion JSON MUST include a `testFile` field with
-the **relative path inside `engine/qa-tests/{{session_id}}/`** of the file
+the **relative path inside `{{qa_test_dir}}`** of the file
 you wrote (e.g. `test.spec.js`, `flow.yaml`). The engine reads this and
 stores it on the session record so the EXECUTE prompt can reference it
 directly. Without `testFile`, EXECUTE falls back to a generic
@@ -87,9 +88,9 @@ Example:
 - commit, push, or open a pull request — sessions are tracked by the
   session record, not a merged PR
 - modify project source — the only file you should write is the test
-  file under `engine/qa-tests/{{session_id}}/`
+  file under `{{qa_test_dir}}`
 - start the managed-spawn yourself — it is already running; query
-  `/api/managed-processes/by-name?name={{managed_spawn_name}}` for the
+  `{{managed_spawn_lookup_url}}` for the
   live port / base URL / health snapshot
 
 ## Failure path (REQUIRED)
@@ -135,12 +136,9 @@ pwd
 ```
 
 `MINIONS_AGENT_CWD` is the engine-resolved worktree root. Prefer it over
-`pwd` for any cwd-sensitive command. The test file path is **relative to
-the Minions root**, not the project worktree — write to
-`<MINIONS_ROOT>/engine/qa-tests/{{session_id}}/`. The Minions root is the
-parent of the project worktree (one level above `MINIONS_AGENT_CWD` for
-project-scoped sessions; equal to `MINIONS_AGENT_CWD` for central
-sessions).
+`pwd` for any cwd-sensitive command. Do not derive the Minions root from
+the project worktree. Write the test only through the injected absolute
+directory `{{qa_test_dir}}`.
 
 ## Findings
 

package/playbooks/qa-session-execute.md

@@ -21,7 +21,7 @@ ingests.
 - **Session id:** `{{session_id}}`
 - **Session phase:** `{{session_phase}}`
 - **Managed-spawn target:** `{{managed_spawn_name}}` (live — query
-  `http://localhost:7331/api/managed-processes/by-name?name={{managed_spawn_name}}`
+  `{{managed_spawn_lookup_url}}`
   for the freshest port / base URL / health).
 - **Test file (relative to `engine/qa-tests/{{session_id}}/`):** `{{test_file}}`
 - **Flows (for context):** {{flows_raw}}
@@ -46,8 +46,11 @@ below.
 
 ### Result sidecar (REQUIRED)
 
-Before exit, write the result sidecar at
-`agents/{{agent_id}}/qa-run-result.json` with this exact shape:
+Store every capture under the injected absolute linked-run directory
+`{{qa_artifacts_dir}}`. Before exit, write the result sidecar at the injected
+absolute path `{{qa_result_sidecar}}`. Artifact `path` values are relative to
+`{{qa_artifacts_dir}}`; preserve nested runner output directories. Use this exact
+shape:
 
 ```json
 {
@@ -57,7 +60,7 @@ Before exit, write the result sidecar at
   "artifacts": [
     {
       "type": "screenshot",
-      "path": "engine/qa-artifacts/{{session_id}}/01-login-form.png",
+      "path": "test-capture-layout/01-login-form.png",
       "label": "Login form rendered",
       "capturedAt": "2026-05-20T20:42:00.000Z"
     }
@@ -114,9 +117,10 @@ green**. Write:
 }
 ```
 
-…AND write a matching `qa-run-result.json` sidecar with `status: "errored"`
-so the qa-runs record terminalizes correctly. The session will transition
-to `failed` with `failureClass: qa-session-execute-failed`.
+…AND write a matching `qa-run-result.json` sidecar to
+`{{qa_result_sidecar}}` with `status: "errored"` so the qa-runs record
+terminalizes correctly. The session will transition to `failed` with
+`failureClass: qa-session-execute-failed`.
 
 ## Working directory
 
@@ -131,10 +135,10 @@ pwd
 ```
 
 `MINIONS_AGENT_CWD` is the engine-resolved worktree root. Prefer it over
-`pwd` for any cwd-sensitive command. The test file path is **relative to
-the Minions root**: full path is
-`<MINIONS_ROOT>/engine/qa-tests/{{session_id}}/{{test_file}}`. Capture
-artifacts to `<MINIONS_ROOT>/engine/qa-artifacts/{{session_id}}/`.
+`pwd` for any cwd-sensitive command. The runner execute brief above resolves
+the drafted test file under the Minions root rather than this disposable
+project worktree. Capture artifacts only under the injected absolute
+`{{qa_artifacts_dir}}` directory, which is keyed by `{{qa_run_id}}`.
 
 ## Long-Running Commands
 
@@ -159,7 +163,7 @@ only after successful completion. Include:
 - Do not modify production code unless explicitly asked.
 - Do not remove worktrees; the engine handles cleanup automatically.
 - Do not start or restart the managed-spawn — the engine owns it.
-- Always emit the `qa-run-result.json` sidecar before exit — even a
+- Always emit `{{qa_result_sidecar}}` before exit — even a
   single-field
   `{"runId": "{{qa_run_id}}", "status": "errored", "summary": "...", "artifacts": []}`
   is better than an absent file.

package/playbooks/qa-validate.md

@@ -36,12 +36,13 @@ block above) and registered a `qaRunId`. Your job:
 3. Execute each step in order. Use Playwright, `curl`, `Invoke-WebRequest`, or
    manual instructions as appropriate for the step's `command` field (if
    present) or `description`.
-4. Save every artifact you produce as a file under
-   `{{qa_artifacts_dir}}` — exactly the path you will reference in the
-   sidecar. Use one of the documented types: `screenshot`, `video`, `log`,
-   `other`.
-5. Before exit, write the result sidecar at
-   `agents/{{agent_id}}/qa-run-result.json` with this exact shape:
+4. Save every artifact you produce as a file under the injected absolute
+   directory `{{qa_artifacts_dir}}`. In the sidecar, record the corresponding
+   Minions-root-relative `engine/qa-artifacts/{{qa_run_id}}/<file>` path shown
+   below so API responses do not expose host filesystem paths. Use one of the
+   documented types: `screenshot`, `video`, `log`, `other`.
+5. Before exit, write the result sidecar at the injected absolute path
+   `{{qa_result_sidecar}}` with this exact shape:
 
 ```json
 {
@@ -51,7 +52,7 @@ block above) and registered a `qaRunId`. Your job:
   "artifacts": [
     {
       "type": "screenshot",
-      "path": "{{qa_artifacts_dir}}/01-login-form.png",
+      "path": "engine/qa-artifacts/{{qa_run_id}}/01-login-form.png",
       "label": "Login form rendered",
       "capturedAt": "2026-05-20T20:42:00.000Z"
     }

package/playbooks/shared-rules.md

@@ -118,6 +118,51 @@ The engine provides a completion report path in the prompt and in `MINIONS_COMPL
 
 **Trust nonce (REQUIRED).** The engine injects a per-spawn cryptographic value into your environment as `MINIONS_COMPLETION_NONCE`. Copy it verbatim into the report's `nonce` field — do not invent, regenerate, or share it with other dispatches. The engine validates the nonce on read; mismatched or (when strict) missing nonces are treated as forged and the dispatch is failed with `failure_class: 'completion-nonce-mismatch'`. See `docs/completion-reports.md` → "Trust boundary" for details.
 
+### Review-learning evidence
+
+For a review or fix dispatch that supplies trusted finding or comment source
+identities, you may include at most eight `reviewLearnings` and at most 32
+`reviewLearningApplications` in the completion report:
+
+```json
+{
+  "reviewLearnings": [{
+    "rule": "State one generalized procedural rule.",
+    "disposition": "accepted-fixed",
+    "source": {
+      "pr": "<canonical dispatch PR id>",
+      "sourceKey": "<trusted finding or comment source key from the dispatch>"
+    },
+    "project": "<dispatch project>",
+    "authorAgent": "<tracked PR author agent>",
+    "applicability": "project-team",
+    "files": ["path/to/file.js"],
+    "symbols": ["symbolName"],
+    "tags": ["review-learning"],
+    "evidence": ["path/to/file.js:123 or commit abc1234"],
+    "confidence": 0.9
+  }],
+  "reviewLearningApplications": [{
+    "id": "M-lesson-id",
+    "outcome": "considered-not-applicable",
+    "evidence": "The task did not touch the lesson's file or symbol scope."
+  }]
+}
+```
+
+Application outcomes are `applied`, `considered-not-applicable`, or
+`contradicted`. Use only the exact trusted source identity supplied with the
+dispatch. Report generalized rules, outcome labels, and observable evidence
+references only. Never include reasoning transcripts or chain-of-thought.
+Malformed optional learning data is diagnosed and dropped without changing an
+otherwise successful fix result. A nonce mismatch or
+`securityFlags.injectionAttempt: true` suppresses both payloads.
+
+An unchanged review-feedback fix must still satisfy
+`reviewFindingResolution`; a `reviewLearnings` entry is not no-op proof. See
+`docs/completion-reports.md` for field types, canonical dispositions, byte
+limits, and the optional `repeatedOf` ID.
+
 For the canonical schema — every field, the `failure_class` enum, `noop:true` semantics, `retryable` / `needs_rerun` shape, and the artifacts array — see `docs/completion-reports.md`. The JSON report is the primary signal; fenced `completion` blocks in stdout are accepted only as a fallback.
 
 ## Minions API access

package/playbooks/test.md

@@ -36,6 +36,10 @@ This task is part of a **shared-branch plan** — other plan items share `{{bran
 {{/shared_branch}}
 {{^shared_branch}}
 If the task asks you to add or modify files, commit those focused changes, push the branch, and create a PR using the same conventions as implement tasks. For pure build/run/verify tasks, do not push or create a PR.
+
+When you do create a PR:
+
+{{pr_create_instructions}}
 {{/shared_branch}}
 
 If a build or test fails, report the error clearly instead of fixing it unless the task explicitly asks for a fix.

package/prompts/cc-system.md

@@ -347,7 +347,7 @@ The `X-CC-Turn-Id` header is the audit trail — the handler stamps it onto the
 
 **Multi-action turns:** make multiple sequential `curl` calls. Each successful state-changing call yields its own chip in the user's reply.
 
-**Errors:** if a `curl` returns 4xx/5xx, surface the error text in your reply so the user sees what went wrong. Don't retry blindly — usually the body explains the missing field.
+**Errors:** the API returns a stable envelope `{ error, code, field?, expected?, allowedValues?, ... }` (4xx) or a generic `internal-error` (5xx). Before crafting a request, prefer discovering a route's accepted inputs and constraints from `GET /api/routes` (each entry publishes its `request` policy/fields, `aliases`, and `negativeTests`) rather than guessing. On a **4xx** (400/404/409/422 — your payload is wrong), self-correct from the structured body — read `code`/`field`/`expected`/`allowedValues`, fix that field, and resend once; surface the message to the user. On a **5xx / 503** a dependency or the engine failed, not your request — do NOT blindly resend in a loop; surface it and, if anything, retry with backoff. See `docs/api-errors.md` for the full contract.
 
 ## Project checkout modes (worktree / live / hybrid)
 

package/skills/check-self-authored-review-comment/SKILL.md

@@ -21,13 +21,13 @@ All Minions agents may post through one GitHub or ADO credential. `viewerDidAuth
 {
   "reviewFindingResolution": {
     "findingId": "<review_finding_id>",
-    "disposition": "already-resolved",
+    "disposition": "satisfied-elsewhere",
     "currentCodeEvidence": "path/to/file.js:123 and the test or behavior proving the disposition"
   }
 }
 ```
 
-5. Use `disposition: "invalid"` only when current-code evidence disproves the claim. A platform-identity observation is not current-code evidence.
+5. Use `disposition: "invalid"` only when current-code evidence disproves the claim. Legacy `already-resolved` remains accepted and is canonicalized to `satisfied-elsewhere`. A platform-identity observation is not current-code evidence.
 
 ## Duplicate findings