@yemi33/minions 0.1.2448 → 0.1.2449

package/minions.js

@@ -16,10 +16,10 @@ const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
 const { execSync } = require('child_process');
-const shared = require('./engine/shared');
+const shared = require('./engine/core/shared');
 const { ENGINE_DEFAULTS, DEFAULT_AGENTS } = shared;
-const projectDiscovery = require('./engine/project-discovery');
-const scheduleBootstrap = require('./engine/schedule-bootstrap');
+const projectDiscovery = require('./engine/planning/project-discovery');
+const scheduleBootstrap = require('./engine/orchestration/schedule-bootstrap');
 
 const MINIONS_HOME = process.env.MINIONS_HOME ? path.resolve(process.env.MINIONS_HOME) : __dirname;
 const CONFIG_PATH = path.join(MINIONS_HOME, 'config.json');
@@ -41,8 +41,34 @@ function cleanupPlaceholderProjects(config) {
   return removed;
 }
 
-function saveConfig(config) {
-  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+const EMPTY_CONFIG = { projects: [], engine: {}, claude: {}, agents: {} };
+function emptyConfig() { return JSON.parse(JSON.stringify(EMPTY_CONFIG)); }
+
+/**
+ * Persist a config.json change through the shared file lock, applying the
+ * mutation to the FRESH on-disk snapshot (W-ms811bme000n475a).
+ *
+ * The previous `loadConfig()` … whole-config `fs.writeFileSync` pattern wrote a
+ * stale config object: anything another writer committed between the read and the
+ * write was silently clobbered. `minions init` runs on every `minions update`
+ * and rewrites `projects[]` it never intended to touch, so a project removed
+ * from the dashboard in that window came straight back. This mirrors the same
+ * fix already applied to removeProject (P-bf05-config-write-race).
+ *
+ * The mutator MUST stay synchronous and fast — it runs while the config lock is
+ * held. Do prompts, runtime detection, and filesystem setup outside it. It may
+ * also be re-run if the lock is compromised, so keep it idempotent.
+ */
+function mutateConfig(mutator) {
+  return shared.mutateJsonFileLocked(CONFIG_PATH, (config) => {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) config = emptyConfig();
+    const next = mutator(config);
+    return next === undefined ? config : next;
+  }, { defaultValue: emptyConfig() });
+}
+
+function _sameLocalPath(entry, resolvedTarget) {
+  return !!(entry && entry.localPath) && path.resolve(entry.localPath) === resolvedTarget;
 }
 
 const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -99,16 +125,13 @@ async function addProject(targetDir) {
     process.exit(1);
   }
 
-  const config = loadConfig();
-  if (!config.projects) config.projects = [];
-
-  // Check if already linked
-  const existing = config.projects.find(p => path.resolve(p.localPath) === target);
+  // Read-only probe for the "already linked" prompt. The authoritative
+  // read-modify-write happens under the config lock further down.
+  const existing = (loadConfig().projects || []).find(p => _sameLocalPath(p, target));
   if (existing) {
     console.log(`  "${existing.name}" is already linked at ${target}`);
     const update = await ask('Update its configuration? (y/N)', 'N');
     if (update.toLowerCase() !== 'y') { rl.close(); return; }
-    config.projects = config.projects.filter(p => path.resolve(p.localPath) !== target);
   }
 
   console.log('\n  Link Project to Minions');
@@ -154,7 +177,7 @@ async function addProject(targetDir) {
   // missing fields up front rather than letting the CLI silently persist a
   // broken project.
   try {
-    require('./engine/projects').assertProjectLinkOk(projectEntry);
+    require('./engine/planning/projects').assertProjectLinkOk(projectEntry);
   } catch (e) {
     console.log(`\n  Error: ${e.message}`);
     if (Array.isArray(e.missing) && e.missing.length > 0) {
@@ -164,18 +187,28 @@ async function addProject(targetDir) {
   }
 
   shared.initializeProjectState(projectEntry);
-  if (existing && String(existing.name || '').toLowerCase() !== String(projectEntry.name || '').toLowerCase()) {
-    scheduleBootstrap.disableProjectGitFetchSchedules(config, existing.name);
-  }
-  config.projects.push(projectEntry);
-  scheduleBootstrap.applyScheduleBootstrap(config, {
-    projectNames: [projectEntry.name],
-    includeHarnessSweep: true,
+  // Re-apply against the FRESH on-disk config: the interactive prompts above
+  // can be open for minutes, and a dashboard/CLI project removal that landed in
+  // that window must not be undone by this write (W-ms811bme000n475a).
+  let totalProjects = 0;
+  mutateConfig(cfg => {
+    if (!Array.isArray(cfg.projects)) cfg.projects = [];
+    const prior = cfg.projects.find(p => _sameLocalPath(p, target));
+    cfg.projects = cfg.projects.filter(p => !_sameLocalPath(p, target));
+    if (prior && String(prior.name || '').toLowerCase() !== String(projectEntry.name || '').toLowerCase()) {
+      scheduleBootstrap.disableProjectGitFetchSchedules(cfg, prior.name);
+    }
+    cfg.projects.push(projectEntry);
+    scheduleBootstrap.applyScheduleBootstrap(cfg, {
+      projectNames: [projectEntry.name],
+      includeHarnessSweep: true,
+    });
+    totalProjects = cfg.projects.length;
+    return cfg;
   });
-  saveConfig(config);
 
   console.log(`\n  Linked "${name}" (${target})`);
-  console.log(`  Total projects: ${config.projects.length}`);
+  console.log(`  Total projects: ${totalProjects}`);
   console.log(`\n  Start the minions from anywhere:`);
   console.log(`    node ${MINIONS_HOME}/engine.js         # Engine`);
   console.log(`    node ${MINIONS_HOME}/dashboard.js      # Dashboard`);
@@ -183,7 +216,7 @@ async function addProject(targetDir) {
 }
 
 function removeProject(target, options = {}) {
-  const { removeProject: doRemove } = require('./engine/projects');
+  const { removeProject: doRemove } = require('./engine/planning/projects');
   // CLI accepts a path; project lookup also matches by name as a convenience
   const result = doRemove(path.resolve(target), options);
   if (!result.ok) {
@@ -315,8 +348,10 @@ async function scanAndAdd({ root, depth } = {}) {
     return;
   }
 
-  const config = loadConfig();
-  const linkedPaths = new Set((config.projects || []).map(p => path.resolve(p.localPath)));
+  // Read-only snapshot used to tag "already linked" in the listing. The
+  // authoritative read-modify-write happens under the config lock further down.
+  const linkedPaths = new Set(
+    (loadConfig().projects || []).filter(p => p && p.localPath).map(p => path.resolve(p.localPath)));
 
   // Enrich repos with auto-discovered metadata
   const enriched = repos.map(repoPath => {
@@ -376,34 +411,57 @@ async function scanAndAdd({ root, depth } = {}) {
 
   console.log(`\n  Adding ${toAdd.length} project(s)...\n`);
 
-  const existingNames = new Set((config.projects || []).map(p => p.name));
+  // Re-apply against the FRESH on-disk config — the selection prompt above can
+  // be open for minutes (W-ms811bme000n475a). Name/path dedupe therefore runs
+  // inside the lock, and initializeProjectState (filesystem work) runs after it.
   const addedProjectNames = [];
-  for (const repo of toAdd) {
-    // Deduplicate names — append -2, -3 etc. if name already taken
-    let name = repo.name;
-    if (existingNames.has(name)) {
-      let i = 2;
-      while (existingNames.has(name + '-' + i)) i++;
-      name = name + '-' + i;
+  const addedEntries = [];
+  let totalProjects = 0;
+  mutateConfig(cfg => {
+    if (!Array.isArray(cfg.projects)) cfg.projects = [];
+    // The mutator can be re-run when the lock is compromised — reset accumulators.
+    addedProjectNames.length = 0;
+    addedEntries.length = 0;
+    const existingNames = new Set(cfg.projects.map(p => p && p.name).filter(Boolean));
+    const existingPaths = new Set(
+      cfg.projects.filter(p => p && p.localPath).map(p => path.resolve(p.localPath)));
+    for (const repo of toAdd) {
+      // Another writer may have linked this path since the scan listing.
+      if (existingPaths.has(path.resolve(repo.path))) continue;
+      // Deduplicate names — append -2, -3 etc. if name already taken
+      let name = repo.name;
+      if (existingNames.has(name)) {
+        let i = 2;
+        while (existingNames.has(name + '-' + i)) i++;
+        name = name + '-' + i;
+      }
+      existingNames.add(name);
+      existingPaths.add(path.resolve(repo.path));
+      const projectEntry = buildProjectEntry({
+        name, description: repo.description, localPath: repo.path,
+        repoHost: repo.host, repositoryId: repo.repositoryId, org: repo.org, project: repo.project,
+        repoName: repo.repoName, mainBranch: repo.mainBranch, prUrlBase: repo.prUrlBase,
+      });
+      cfg.projects.push(projectEntry);
+      addedProjectNames.push(projectEntry.name);
+      addedEntries.push(projectEntry);
     }
-    existingNames.add(name);
-    const projectEntry = buildProjectEntry({
-      name, description: repo.description, localPath: repo.path,
-      repoHost: repo.host, repositoryId: repo.repositoryId, org: repo.org, project: repo.project,
-      repoName: repo.repoName, mainBranch: repo.mainBranch, prUrlBase: repo.prUrlBase,
-    });
-    shared.initializeProjectState(projectEntry);
-    config.projects.push(projectEntry);
-    addedProjectNames.push(projectEntry.name);
-    console.log(`  + ${name} (${repo.path})`);
+    if (addedProjectNames.length > 0) {
+      scheduleBootstrap.applyScheduleBootstrap(cfg, {
+        projectNames: addedProjectNames,
+        includeHarnessSweep: true,
+      });
+    }
+    totalProjects = cfg.projects.length;
+    return cfg;
+  });
+
+  for (const entry of addedEntries) {
+    shared.initializeProjectState(entry);
+    console.log(`  + ${entry.name} (${entry.localPath})`);
   }
 
-  scheduleBootstrap.applyScheduleBootstrap(config, {
-    projectNames: addedProjectNames,
-    includeHarnessSweep: true,
-  });
-  saveConfig(config);
-  console.log(`\n  Done. ${config.projects.length} total project(s) linked.`);
+  console.log(`\n  Done. ${totalProjects} total project(s) linked.`);
   console.log(`  Run "minions list" to verify.\n`);
   rl.close();
 }
@@ -413,39 +471,51 @@ async function scanAndAdd({ root, depth } = {}) {
 const [cmd, ...rest] = process.argv.slice(2);
 
 async function initMinions({ skipScan = false, scanRoot, scanDepth } = {}) {
-  const config = loadConfig();
-  if (!config.projects) config.projects = [];
-  const removedPlaceholders = cleanupPlaceholderProjects(config);
-  const hadConfiguredDefaultCli = config.engine?.defaultCli !== undefined;
-  // Merge defaults — fills in new fields from upgrades while preserving user customizations
-  if (!config.engine) config.engine = {};
-  for (const [k, v] of Object.entries(ENGINE_DEFAULTS)) {
-    if (k === 'defaultCli') continue;
-    if (config.engine[k] === undefined) config.engine[k] = v;
-  }
-  shared.pruneDefaultClaudeConfig(config);
-  if (!config.agents || Object.keys(config.agents).length === 0) {
-    config.agents = { ...DEFAULT_AGENTS };
-  }
+  // Runtime detection shells out (`where` / `which`), so it must run OUTSIDE the
+  // config lock — lock callbacks stay synchronous and fast.
+  const hadConfiguredDefaultCli = loadConfig().engine?.defaultCli !== undefined;
+  const detected = hadConfiguredDefaultCli ? [] : _detectAvailableRuntimes();
+
+  // W-ms811bme000n475a: merge into the FRESH on-disk config under the lock.
+  // `minions init` runs on every `minions update`; the previous stale-snapshot
+  // rewrite resurrected projects that were unlinked while it was running, even
+  // though init never intends to touch `projects[]`.
+  let removedPlaceholders = 0;
+  let pinnedDefaultCli = null;
+  mutateConfig(config => {
+    removedPlaceholders = 0;
+    pinnedDefaultCli = null;
+    if (!config.projects) config.projects = [];
+    removedPlaceholders = cleanupPlaceholderProjects(config);
+    // Merge defaults — fills in new fields from upgrades while preserving user customizations
+    if (!config.engine) config.engine = {};
+    for (const [k, v] of Object.entries(ENGINE_DEFAULTS)) {
+      if (k === 'defaultCli') continue;
+      if (config.engine[k] === undefined) config.engine[k] = v;
+    }
+    shared.pruneDefaultClaudeConfig(config);
+    if (!config.agents || Object.keys(config.agents).length === 0) {
+      config.agents = { ...DEFAULT_AGENTS };
+    }
 
-  // Auto-detect available runtime CLIs and pin engine.defaultCli to whichever
-  // is installed. Only set if the user hasn't already configured one — never
-  // overwrite an explicit choice on `init --force` upgrades.
-  if (!hadConfiguredDefaultCli) {
-    const detected = _detectAvailableRuntimes();
-    if (detected.length === 1) {
-      config.engine.defaultCli = detected[0];
-      console.log(`\n  ✓ Detected ${detected[0]} CLI — set as fleet default runtime`);
-    } else if (detected.length > 1) {
-      // Prefer the canonical fleet default when it is installed.
-      config.engine.defaultCli = detected.includes(ENGINE_DEFAULTS.defaultCli)
-        ? ENGINE_DEFAULTS.defaultCli
-        : detected[0];
-      console.log(`\n  ✓ Detected ${detected.join(' + ')} — fleet default set to ${config.engine.defaultCli}`);
+    // Auto-detect available runtime CLIs and pin engine.defaultCli to whichever
+    // is installed. Only set if the user hasn't already configured one — never
+    // overwrite an explicit choice on `init --force` upgrades. Re-checked here
+    // because another writer may have pinned it since the pre-lock probe.
+    if (config.engine.defaultCli === undefined && detected.length > 0) {
+      config.engine.defaultCli = detected.length === 1
+        ? detected[0]
+        : (detected.includes(ENGINE_DEFAULTS.defaultCli) ? ENGINE_DEFAULTS.defaultCli : detected[0]);
+      pinnedDefaultCli = config.engine.defaultCli;
     }
     // If nothing is detected, leave defaultCli unset so the engine uses its canonical default.
+    return config;
+  });
+  if (pinnedDefaultCli) {
+    console.log(detected.length === 1
+      ? `\n  ✓ Detected ${detected[0]} CLI — set as fleet default runtime`
+      : `\n  ✓ Detected ${detected.join(' + ')} — fleet default set to ${pinnedDefaultCli}`);
   }
-  saveConfig(config);
   console.log(`\n  Minions initialized at ${MINIONS_HOME}`);
   console.log(`  Config, agents, and engine defaults created.\n`);
 

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2448",
+  "version": "0.1.2449",
   "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"
   },
   "scripts": {
-    "package:check": "node tools/check-package-boundary.js public",
-    "package:prepare:public": "node tools/prepare-package.js public",
-    "package:prepare:internal": "node tools/prepare-package.js internal",
+    "package:check": "node scripts/check-package-boundary.js public",
+    "package:prepare:public": "node scripts/prepare-package.js public",
+    "package:prepare:internal": "node scripts/prepare-package.js internal",
+    "package:drift:check": "node scripts/reconcile-publish-drift.js --check",
+    "package:drift:apply": "node scripts/reconcile-publish-drift.js --apply",
     "dev": "node bin/minions.js --dev restart",
     "dev:start": "node bin/minions.js --dev start",
     "dev:stop": "node bin/minions.js --dev stop",
@@ -50,6 +52,7 @@
     "dashboard-build.js",
     "dashboard.js",
     "docs/",
+    "engine/README.md",
     "engine/**/*.js",
     "engine.js",
     "knowledge/agents/*.md",
@@ -57,7 +60,8 @@
     "playbooks/",
     "prompts/",
     "routing.md",
-    "skills/"
+    "skills/",
+    "watch-plugins/"
   ],
   "repository": {
     "type": "git",
@@ -69,7 +73,7 @@
   },
   "devDependencies": {
     "@playwright/test": "^1.58.2",
-    "eslint": "^9.39.4",
+    "eslint": "^10.8.0",
     "eslint-plugin-no-unsanitized": "^4.1.5"
   },
   "publishConfig": {

package/playbooks/_pr-description-audit.md

@@ -1,7 +1,7 @@
 # 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)
+> fragments**. The engine renderer (`engine/agents/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
@@ -65,108 +65,137 @@ 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 (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.
+## Visual evidence handling — screenshots + recordings (introduce AND refresh for visual changes)
+
+Visual evidence is a **default behavior for UI changes on ANY project**, not a
+minions-only nicety. For a PR that contains a **meaningful visual/UI change** —
+web front-ends, dashboards, mobile webviews, or any rendered surface a user sees
+— proactively CAPTURE evidence and EMBED it directly in the PR description; do
+**not** rely only on the OPG `Visual evidence capture` CI bot (that bot stays
+as-is and is minions-specific; this is additive, cross-project PR-body evidence).
+When the existing description already embeds `![alt](url)` refs for a view this
+dispatch touched, refresh them the same way. Decide "is this a visual change?"
+from whether the diff changes a **rendered UI surface**, NOT from repo-specific
+paths.
+
+Capture **both** where applicable:
+
+- **Screenshots** — a BEFORE/AFTER pair for visual FIXES; an AFTER-only shot for
+  NEW UI.
+- **Screen recordings / video** — for interactive, animated, or multi-step flows
+  (hover/expand, drag, wizard steps, transitions). Playwright records video per
+  browser context; save the resulting file alongside the screenshots.
+
+**How to capture — resolution order (harness first, then the minions skill).**
+
+1. **Harness first.** Consult the TARGET repo's own instructions for how it runs
+   its UI and captures evidence before inventing a command: `AGENTS.md`,
+   `CLAUDE.md`, `README`/`CONTRIBUTING`, a project-local playbook override under
+   `projects/<name>/playbooks/`, or a project-embedded skill under
+   `.claude/skills` / `.github/skills` / `.agents/skills`. The engine already
+   surfaces this harness plumbing read-only — `engine/agents/harness-context.js` and
+   `GET /api/harness/diagnostics` — so ground your capture on what the repo
+   actually declares; don't guess.
+2. **Fall back to the minions Playwright skill.** If the target repo has no
+   visual-evidence instructions, use Minions' own project-agnostic
+   `capture-web-evidence` skill (`.claude/skills/capture-web-evidence/SKILL.md`),
+   which drives Playwright (Playwright MCP when available, else the Playwright
+   CLI) against any web or mobile-webview UI.
 
 **MANDATORY GATE — UI-surface diffs REQUIRE screenshots.** Screenshot capture +
 embed is a **required completion gate**, not a nicety, for any dispatch whose diff
 modifies a **rendered UI surface** — e.g. files under `dashboard/`,
 `dashboard/slim/`, `dashboard/pages/`, `dashboard/js/`, `dashboard/styles.css`, or
 ANY change that alters what a dashboard page/route renders
-(layout/CSS/markup/new UI). For such a diff you **MUST** capture and embed AFTER
-screenshots (BEFORE/AFTER for visual FIXES, AFTER-only for NEW UI) for the PR to be
-considered complete. Omitting screenshots on a UI-surface diff **without a recorded
-hard-failure reason makes the PR incomplete** — "I judged it not visual enough" is
-**NOT** a valid skip when the diff touches those paths. The ONLY legitimate skips are
-genuine hard failures: the dev server will not start after a real attempt, Playwright
-MCP is unavailable, the route 404s, or upload/attachment auth fails. Record any such
-skip in `meta.descriptionAudit.result` as `screenshots-skipped (<specific-reason>)`.
-
-**Scope guard — which changes get screenshots.** Only meaningful visual/UI
+(layout/CSS/markup/new UI). This is the minions-dashboard instance of the
+cross-project default above and is **not** weakened by it. For such a diff you
+**MUST** capture and embed AFTER screenshots (BEFORE/AFTER for visual FIXES,
+AFTER-only for NEW UI) for the PR to be considered complete. Omitting screenshots
+on a UI-surface diff **without a recorded hard-failure reason makes the PR
+incomplete** — "I judged it not visual enough" is **NOT** a valid skip when the
+diff touches those paths. The ONLY legitimate skips are genuine hard failures: the
+dev server will not start after a real attempt, Playwright MCP is unavailable, the
+route 404s, or upload/attachment auth fails. Record any such skip in
+`meta.descriptionAudit.result` as `screenshots-skipped (<specific-reason>)`.
+
+**Scope guard — which changes get visual evidence.** 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.
+layout/CSS, and the equivalent rendered surfaces of other projects.
+Skip backend-only, engine-logic, text/prose-only, analysis, and docs changes —
+those get NO screenshots or recordings (they add no signal). Use a BEFORE/AFTER
+pair for layout/visual FIXES; an AFTER-only shot for NEW UI; add a recording only
+for interactive/animated flows.
+
+**Capture.** Detect the project's run command generically — from the repo harness
+(step 1 above) or from a `package.json` script named `dev`, `start`, or `serve`
+(or the repo's documented preview command). Do **not** hardcode a per-repo build
+command. With Playwright available:
+
+1. Spin up the project's dev/preview server with a detached handoff (see
+   `shared-rules.md` → "Long-Running Commands"). Record PID + log path + URL +
+   stop command.
+2. Drive Playwright to the changed route/view at a **normal desktop viewport**;
+   for **mobile webviews**, also capture at a mobile device-emulation viewport
+   (e.g. Playwright's `devices['iPhone 13']` or an explicit small viewport) and
+   screenshot the section that changed. For interactive flows, enable video
+   recording, drive the interaction, then save the video. Save raw PNGs/videos to
+   `agents/<id>/screenshots/` ONLY (recordings under a `recordings/` subdir).
+   **NEVER `git add` a PNG** or a video — committing captured evidence 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')
-```
+on private repositories and never commits PNGs to the source branch.
+
+1. Resolve `<owner>/<repo>` from the current PR and GET-verify that exact slug.
+2. Enumerate configured `gh` accounts without changing global auth. For each,
+   build a per-command `GH_TOKEN` and probe the exact slug; select only an
+   account whose repository response grants push permission. Fail closed when
+   none does. **NEVER run `gh auth switch` or hardcode an operator login.**
+3. Set `TAG=pr-<num>-visual` and explicitly list this dispatch's PNG (and, for
+   interactive flows, video) files.
+4. Query `gh release view "$TAG" --repo <owner>/<repo>` first. If the exact tag
+   exists, run `gh release upload "$TAG" <files> --clobber`; if it returns a
+   verified not-found response, run `gh release create`. Do not reinterpret an
+   arbitrary create failure as permission to overwrite assets.
+5. Resolve each asset with `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>`.
+`gh pr edit <num> --repo <owner>/<repo> --body-file <file>`. Recordings upload as
+assets on the same release; embed them as a plain markdown link (video files do
+not render inline) — `[<view> (recording)](<url>)`.
 
 **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.
+`PUT /pullRequests/<id>/attachments/<filename>` with the PNG (or video) bytes,
+then reference the returned URL in the description. This now applies to
+newly-introduced screenshots and recordings 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.
+`result: "screenshots-skipped (dev-server-unavailable)"`). Screenshots and
+recordings NEVER land in the repo — `agents/<id>/screenshots/` only (videos under
+a `recordings/` subdir); never `git add` a PNG or a video.
 
 ## Out-of-scope guardrails
 
-- Only screenshot **meaningful visual/UI changes** (see the scope guard above);
-  skip backend/engine/text/analysis/docs changes — they add no signal.
+- Only capture visual evidence for **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 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.
+- Don't fail the work item on a screenshot, recording, or upload/attachment
+  failure — degrade gracefully and record the skip.
+- Screenshots and recordings **never** land in the repo. Save raw PNGs only under
+  `agents/<id>/screenshots/` (videos under a `recordings/` subdir). No `git add`
+  of any PNG or video, ever.
 - Never run `gh auth switch`; build a per-command `GH_TOKEN` for the repo
   owner's account.
 
@@ -193,9 +222,12 @@ 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.
+and list the embedded asset URLs in `newScreenshots`. When you also (or only)
+attach a **screen recording**, use `result: "recordings-introduced"` (or combine,
+e.g. `"screenshots-introduced+recordings-introduced"`) and list the video asset
+URLs in `newScreenshots` alongside the images. 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`

package/playbooks/build-fix-complex.md

@@ -78,6 +78,8 @@ Use subagents only for genuinely parallel, independent tasks (e.g., editing file
 
 Before starting work, run `git status` and verify the worktree is clean and on the expected branch (`{{pr_branch}}`). If the worktree is dirty or on the wrong branch, report the issue and stop.
 
+An untracked root-level `.minions-worktree` entry is expected Minions orchestration metadata, not source dirt. Do not delete or modify the marker. Any other status entry, including staged, modified, deleted, or other untracked files, means the worktree is dirty.
+
 ## Validation
 
 Before pushing, prove the fix did not introduce regressions: