@yemi33/minions 0.1.2048 → 0.1.2050

package/dashboard/slim.html

@@ -919,10 +919,10 @@
       var flags = (data && data.features) || [];
 
       // Build the body as a document fragment so we avoid .innerHTML for
-      // the dynamic parts (SEC-03 ratchet — see DYNAMIC_INNERHTML_BASELINE
-      // in test/unit.test.js). Static intro paragraph uses innerHTML
-      // because it carries a <code> tag and is a pure string literal
-      // (exempted by _isStaticInnerHtmlRhs).
+      // the dynamic parts. Static intro paragraph uses innerHTML because
+      // it carries a <code> tag and is a pure string literal (exempted
+      // by the no-unsanitized rule).
+      // (Comment retained for legibility; ratchet test is being retired.)
       var intro = document.createElement('p');
       intro.innerHTML = 'Toggle <code>slim-ux</code> off to return to the original dashboard. Advanced settings (agents, projects, runtime) live there for now.';
       var frag = document.createDocumentFragment();
@@ -1342,8 +1342,8 @@
   // Zero-project: a hint to add one. Selection persists per-browser in
   // localStorage and is included in every /api/command-center/stream call.
   // Build the "+ Add" button as a real DOM node (was an HTML string + innerHTML
-  // injection — SEC-03 ratchet prefers we avoid that pattern, see
-  // test/unit.test.js DYNAMIC_INNERHTML_BASELINE).
+  // injection — the no-unsanitized/property rule prefers we avoid that pattern
+  // entirely for dynamic data).
   function makeContextAddBtn() {
     var btn = document.createElement('button');
     btn.type = 'button';
@@ -1911,8 +1911,8 @@
       listEl.innerHTML = '<div class="history-empty">Nothing has happened yet — Command Center will fill this in.</div>';
       return;
     }
-    // Build the feed as DOM nodes so SEC-03's .innerHTML ratchet stays happy
-    // (test/unit.test.js DYNAMIC_INNERHTML_BASELINE). Each event becomes
+    // Build the feed as DOM nodes to avoid dynamic .innerHTML
+    // (no-unsanitized/property rule). Each event becomes
     // .history-item > .history-head + .history-title + .history-meta, with
     // the optional PR "open" link constructed as a real <a> node.
     var frag = document.createDocumentFragment();

package/dashboard/styles.css

@@ -710,6 +710,41 @@
 
   .modal-body { padding: var(--space-7) var(--space-8); overflow-y: auto; overflow-x: auto; white-space: pre-wrap; font-size: var(--text-md); line-height: 1.7; color: var(--muted); font-family: Consolas, monospace; }
 
+  /* ── Settings: left-rail tabbed layout (W-mpmwxkcn000646cc) ─────────────
+     Replaces the prior flat scroll of every engine.* knob with a Slack/VS-Code-style
+     vertical nav + per-tab pane. Search input filters control rows across all tabs
+     by data-search attribute. .modal.modal-wide is added by openSettings() so the
+     rail + content fit comfortably side-by-side. */
+  .modal-body.settings-body { padding: 0; white-space: normal; font-size: var(--text-md); line-height: 1.45; color: var(--text); font-family: 'Segoe UI', system-ui, sans-serif; }
+  .settings-layout { display: flex; min-height: 480px; max-height: calc(80vh - 64px); }
+  .settings-rail { width: 220px; min-width: 220px; background: var(--surface2); border-right: 1px solid var(--border); display: flex; flex-direction: column; overflow: hidden; }
+  .settings-search-wrap { padding: var(--space-5) var(--space-5) var(--space-4); border-bottom: 1px solid var(--border); }
+  .settings-search { width: 100%; padding: var(--space-3) var(--space-4); background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius-sm); color: var(--text); font-size: var(--text-md); font-family: inherit; }
+  .settings-search:focus { outline: none; border-color: var(--blue); }
+  .settings-rail-nav { flex: 1; overflow-y: auto; padding: var(--space-3) 0; }
+  .settings-rail-btn { display: flex; align-items: center; justify-content: space-between; width: 100%; padding: var(--space-3) var(--space-6); background: transparent; border: none; border-left: 3px solid transparent; color: var(--muted); font-size: var(--text-md); font-family: inherit; cursor: pointer; text-align: left; transition: all var(--transition-fast); }
+  .settings-rail-btn:hover { color: var(--text); background: var(--surface); }
+  .settings-rail-btn.active { color: var(--blue); border-left-color: var(--blue); background: var(--surface); font-weight: 600; }
+  .settings-rail-btn.featured { color: var(--text); }
+  .settings-rail-btn.featured.active { color: var(--blue); }
+  .settings-rail-btn.no-match { opacity: 0.3; }
+  .settings-rail-btn .match-count { font-size: var(--text-xs); color: var(--blue); background: var(--bg); border-radius: var(--radius-xl); padding: 1px 6px; min-width: 18px; text-align: center; }
+  .settings-content { flex: 1; overflow-y: auto; padding: var(--space-7) var(--space-8); min-width: 0; }
+  .settings-pane { display: none; }
+  .settings-pane.active { display: block; }
+  .settings-pane h3 { font-size: var(--text-xl); color: var(--blue); margin-bottom: var(--space-3); font-weight: 600; }
+  .settings-pane .settings-pane-sub { font-size: var(--text-base); color: var(--muted); margin-bottom: var(--space-7); }
+  .settings-pane h4 { font-size: var(--text-lg); color: var(--text); margin: var(--space-7) 0 var(--space-4); font-weight: 600; }
+  .settings-grid-2 { display: grid; grid-template-columns: 1fr 1fr; gap: var(--space-4); }
+  .settings-grid-3 { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: var(--space-4); }
+  .settings-stack { display: flex; flex-direction: column; gap: var(--space-3); }
+  .settings-row { padding: 2px 0; }
+  .settings-row.no-match { display: none; }
+  .settings-row.match-highlight { background: rgba(88,166,255,0.08); border-left: 2px solid var(--blue); padding-left: var(--space-3); border-radius: var(--radius-sm); }
+  .settings-body.searching .settings-pane { display: block; }
+  .settings-body.searching .settings-pane.no-match { display: none; }
+  .settings-pane-empty { font-size: var(--text-base); color: var(--muted); padding: var(--space-6) 0; font-style: italic; }
+
   /* Responsive: tablet / narrow window */
   @media (max-width: 1100px) {
     .layout { grid-template-columns: 1fr; }

package/docs/deprecated.json

@@ -1,28 +1,77 @@
 [
   {
     "id": "config-poll-key-migration",
-    "location": "engine/queries.js:123-162",
+    "location": "engine/queries.js:126-163",
     "function": "migrateDeprecatedConfigPollKeysOnce",
     "reason": "One-time boot migration that renames legacy engine config keys (adoPollStatusEvery → prPollStatusEvery, adoPollCommentsEvery → prPollCommentsEvery). Keys were renamed on 2026-04-16; this shim ensures any persisted config.json on a long-lived host gets transparently rewritten on next boot.",
     "targetRemovalDate": "2026-08-09",
-    "notes": "Safe to delete on or after 2026-08-09 (3 months after the rename) once we are confident every engine has rebooted at least once and the closure-flagged migration (_configPollKeyMigrationChecked at line 123) is no longer reachable on any persisted config. Removal is one function + the call site in getConfig() at engine/queries.js:165."
+    "notes": "Safe to delete on or after 2026-08-09 (3 months after the rename) once we are confident every engine has rebooted at least once and the closure-flagged migration (_configPollKeyMigrationChecked at line 124) is no longer reachable on any persisted config. Removal is one function + the call site in getConfig() at engine/queries.js:166."
   },
   {
     "id": "legacy-done-aliases",
-    "location": "engine/cleanup.js:970-972",
+    "location": "engine/cleanup.js:1052-1054",
     "constants": ["LEGACY_DONE_ALIASES", "LEGACY_NEEDS_REVIEW_STATUS"],
     "reason": "Read-side tolerance: cleanup sweep auto-migrates four obsolete work-item / PRD status strings ('in-pr', 'implemented', 'complete', 'needs-human-review') to the canonical 'done' / 'failed' values. The aliases are no longer written anywhere in the engine; the constants exist only to repair stale on-disk values from old engine versions.",
     "targetRemovalDate": null,
-    "notes": "Keep indefinitely until telemetry / a sweep log shows zero migrations performed for 30 consecutive days across all known projects (work-items.json + prd/*.json). At that point the constants and both _migrateLegacyItem branches in engine/cleanup.js (definitions at :970-972; usage at :973-1000 for work items and :1051-1057 for PRD missing_features) can be deleted. Total cost on disk today: 4 strings."
+    "notes": "Keep indefinitely until telemetry / a sweep log shows zero migrations performed for 30 consecutive days across all known projects (work-items.json + prd/*.json). At that point the constants and both _migrateLegacyItem branches in engine/cleanup.js (definitions at :1052-1054; usage at :1055-1071 for work items and :1156-1162 for PRD missing_features) can be deleted. Total cost on disk today: 4 strings."
   },
   {
     "id": "completion-fallback-parsers",
     "description": "parseStructuredCompletion and parseCompletionFieldSummary in engine/lifecycle.js",
     "file": "engine/lifecycle.js",
-    "lines": "2747, 2848",
-    "telemetryGate": "_engine.completionFallbacks must read 0 across sweep window",
+    "lines": "2856, 3054",
+    "telemetryGate": "_engine.completionFallbacks must read 0 (both fenced and summary counters) across sweepWindowDays starting from sweepStartDate",
+    "sweepWindowDays": 14,
+    "sweepStartDate": "2026-05-27",
+    "sweepRationale": "14 days matches the dead-code audit cadence (one full weekly audit cycle plus a buffer week). Policy decision pending confirmation in open-question #1 of the 2026-05-27 Bug Audit Review meeting conclusion — if the human teammate prefers a different cadence, repin this field and the matching enforcingSweepWindowTest fixture.",
     "enforcingTest": "test/unit/completion-fallback-telemetry.test.js:217-234",
-    "notes": "Do NOT set removedAt until telemetry confirms zero usage"
+    "enforcingSweepWindowTest": "test/unit/completion-fallback-sweep-window.test.js",
+    "notes": "Do NOT set removedAt until telemetry confirms zero usage across the sweepWindowDays from sweepStartDate. The follow-up code-removal PR (dropping parseStructuredCompletion at engine/lifecycle.js:2856, parseCompletionFieldSummary at :3054, and the gated fallback at :3852-3877) is dispatched separately once the window is observed clean."
+  },
+  {
+    "id": "config-claude-binary-override",
+    "description": "Legacy `config.claude.binary` runtime-resolution override. Older `minions init` versions persisted a `config.claude.binary` field that pointed the Claude runtime at a specific binary path. The runtime adapter still honors this override on every Claude spawn; the engine emits a `deprecated-config-claude` warning at config-load time but does NOT delete the override, so the override branch in claude.js is load-bearing for any install that still carries a non-default value.",
+    "code": [
+      { "file": "engine/runtimes/claude.js", "lines": "82-93", "note": "resolveBinary() respects config.claude.binary on every Claude spawn (probes npm package dir or direct binary path)" },
+      { "file": "engine/shared.js", "lines": "2311-2326", "note": "warnings.push({ id: 'deprecated-config-claude' }) — surface-only; never deletes the override" },
+      { "file": "engine/shared.js", "lines": "2770-2774", "note": "DEFAULT_CLAUDE.binary baseline that the warning + prune logic compares against" }
+    ],
+    "removalGate": "Telemetry: the `deprecated-config-claude` warning emitted at engine/shared.js:2321-2324 must report zero hits across all known engines for >=30 consecutive days, AND a sweep of every persisted config.json must show no `config.claude.binary` value that diverges from DEFAULT_CLAUDE.binary. Only then is the override branch in resolveBinary() (engine/runtimes/claude.js:82-93) removable, along with the `_deprecatedConfigClaudeFields` membership for `binary` and the warning emitter at engine/shared.js:2311-2326.",
+    "targetRemovalDate": null,
+    "notes": "Do NOT set targetRemovalDate — removal must be signal-gated, not calendar-gated. This entry is paired with `prune-default-claude-config`: the prune strips DEFAULT-matching values but intentionally preserves user overrides, which is precisely why the override branch in claude.js stays reachable. Removing the override before the prune entry's gate clears would silently break installs that still rely on a custom binary path."
+  },
+  {
+    "id": "legacy-cc-model-migration",
+    "description": "applyLegacyCcModelMigration: in-memory shim that promotes legacy `engine.ccModel` to `engine.defaultModel` when defaultModel is unset, so single-model installs keep working after the runtime fleet refactor (P-3b8e5f1d). No on-disk rewrite — the persisted config.json continues to carry the legacy `ccModel` field. Called unconditionally on every engine boot from cli.start().",
+    "code": [
+      { "file": "engine/shared.js", "lines": "2236", "note": "applyLegacyCcModelMigration definition (function signature + once-per-process flag via _resetLegacyCcModelMigrationFlag)" },
+      { "file": "engine/cli.js", "lines": "471-472", "note": "Boot call site inside start(); wrapped in try/catch so a migration failure cannot block startup" },
+      { "file": "CLAUDE.md", "lines": "316", "note": "Architectural documentation calling out the in-memory promotion contract" },
+      { "file": "docs/slim-ux/concepts.md", "lines": "671", "note": "Surface-level concepts doc cross-reference" },
+      { "file": "test/unit.test.js", "lines": "19402", "note": "Source-inspection test pinning the CLAUDE.md description against the function name" },
+      { "file": "test/unit/runtime-fleet-helpers.test.js", "lines": "209-254", "note": "Behavioural unit tests (promotion, no-op when defaultModel set, no-op when ccModel unset, empty-string handling, once-only logging, null-safety)" },
+      { "file": "test/unit/runtime-fleet-helpers.test.js", "lines": "500-505", "note": "Source-inspection test pinning the cli.js boot call site" }
+    ],
+    "removalGate": "Telemetry: the once-per-boot deprecation log line emitted by applyLegacyCcModelMigration (via the injected logger at engine/shared.js:2236) must show zero promotion events across all known engines for >=30 consecutive days, AND a sweep of every persisted config.json must confirm no `engine.ccModel` field remains. Once both conditions hold, removal deletes the function + _resetLegacyCcModelMigrationFlag export at engine/shared.js:4977, the boot call at engine/cli.js:471-472, the CLAUDE.md:316 paragraph and docs/slim-ux/concepts.md:671 reference, and the tests at runtime-fleet-helpers.test.js:209-254 + :500-505 + unit.test.js:19402.",
+    "targetRemovalDate": null,
+    "notes": "Do NOT set targetRemovalDate — gating is signal-based. The function is silent on no-op (returns false without logging), so the meaningful telemetry signal is the absence of the promotion log line over the sweep window, NOT the absence of function invocations (cli.js calls it every boot regardless)."
+  },
+  {
+    "id": "prune-default-claude-config",
+    "description": "pruneDefaultClaudeConfig: active sanitizer that strips generated `config.claude.{binary,outputFormat,allowedTools,permissionMode}` defaults from persisted config.json so the `deprecated-config-claude` warning stops tripping on stale defaults left by older `minions init` versions. Sub-cluster of `config-claude-binary-override` — the prune deliberately preserves non-default user overrides (binary/allowedTools), which is what keeps the override branch in engine/runtimes/claude.js load-bearing.",
+    "code": [
+      { "file": "engine/shared.js", "lines": "2776-2809", "note": "pruneDefaultClaudeConfig definition: preserves non-default binary/allowedTools, always strips permissionMode + outputFormat" },
+      { "file": "engine/shared.js", "lines": "4989", "note": "Module export entry" },
+      { "file": "dashboard.js", "lines": "196", "note": "Called when loading config for the dashboard UI" },
+      { "file": "dashboard.js", "lines": "8753", "note": "Called during first config save handler" },
+      { "file": "dashboard.js", "lines": "8983", "note": "Called during second config save path" },
+      { "file": "dashboard.js", "lines": "9102", "note": "Called during third config save path" },
+      { "file": "minions.js", "lines": "385", "note": "Called during CLI init/update flow" },
+      { "file": "test/unit.test.js", "lines": "2153-2196", "note": "Behavioural unit tests (default strip, override preservation, outputFormat unconditional strip) + dashboard call-site source pin" },
+      { "file": "test/unit/runtime-fleet-helpers.test.js", "lines": "546", "note": "Source-inspection test pinning the dashboard handler call site" }
+    ],
+    "removalGate": "Telemetry: pruneDefaultClaudeConfig must return false (no mutation) for every call across all known engines for >=30 consecutive days (add an `_engine.pruneDefaultClaudeConfigStrips` counter if needed to observe this), AND the parent `config-claude-binary-override` entry must have already cleared its own gate. The dependency is strict: removing the prune while users still rely on the override branch would surface the `deprecated-config-claude` warning on every stale generated default. Once both conditions hold, removal is the function definition (engine/shared.js:2776-2809), the export at :4989, all 5 call sites (dashboard.js:196, :8753, :8983, :9102; minions.js:385), and the tests at unit.test.js:2153-2196 + runtime-fleet-helpers.test.js:546.",
+    "targetRemovalDate": null,
+    "notes": "Do NOT set targetRemovalDate — gating is signal-based AND ordered. This entry MUST NOT be removed before `config-claude-binary-override` clears its gate, otherwise installs with stale defaults will flood the deprecation channel until their next config save. The 5 call sites form a complete coverage net: load (dashboard.js:196 + minions.js:385) + save (dashboard.js:8753/8983/9102), so any code path that touches config.json runs the sanitizer."
   }
 ]
-

package/engine/lifecycle.js

@@ -4685,7 +4685,6 @@ module.exports = {
   checkForLearnings,
   extractSkillsFromOutput,
   updateAgentHistory,
-  reviewFeedbackSourceMatches,
   createReviewFeedbackForAuthor,
   updateMetrics,
   parseAgentOutput,

package/engine/queries.js

@@ -531,6 +531,11 @@ function getAgents(config) {
     // → engine.defaultCli → 'copilot'. Surfaced so the dashboard can show a
     // runtime tag next to the agent name.
     const runtime = shared.resolveAgentCli(a, config.engine || {});
+    // Resolve the model alongside the runtime so the dashboard can render a
+    // sibling chip (W-mpmwxk4y00053271). `resolveAgentModel` returns
+    // `undefined` when neither the per-agent override nor `engine.defaultModel`
+    // is set, which the renderer treats as "runtime default" and omits.
+    const model = shared.resolveAgentModel(a, config.engine || {}) || null;
     const inboxFiles = allInboxFiles.filter(f => f.includes(a.id));
     let steeringInboxFiles = [];
     try { steeringInboxFiles = steering.listUnreadSteeringMessages(a.id); } catch { steeringInboxFiles = []; }
@@ -552,7 +557,7 @@ function getAgents(config) {
     const chartered = fs.existsSync(path.join(AGENTS_DIR, a.id, 'charter.md'));
     if (lastAction.length > 120) lastAction = lastAction.slice(0, 120) + '...';
     return {
-      ...a, runtime, status: s.status, lastAction,
+      ...a, runtime, model, status: s.status, lastAction,
       currentTask: (s.task || '').slice(0, 200),
       // P-w2c8d1e7 — Phase 1.2: surface the active dispatch id so watch
       // captureState can snapshot it for currentDispatchId-aware predicates.
@@ -1236,8 +1241,16 @@ function getWorkItems(config) {
       }
     }
     if (!item._pr) {
-      // Derive from PR.prdItems (single source of truth)
-      const linkedPr = allPrs.find(p => (p.prdItems || []).includes(item.id));
+      // Derive from PR.prdItems (single source of truth), then fall back to
+      // branch identity. The branch fallback heals decomposed-child WIs whose
+      // PR-opening agent only stamped the parent id into prdItems — branch
+      // names (`work/<wi-id>`) are unique per WI within a project, so a
+      // branch hit is as authoritative as a prdItems hit. Scoped to the same
+      // project so cross-repo branch collisions don't false-link.
+      // (W-mpn0b76200044eed)
+      const itemProject = item.project || item._source;
+      const linkedPr = allPrs.find(p => (p.prdItems || []).includes(item.id))
+        || (item.branch && allPrs.find(p => p.branch === item.branch && p._project === itemProject));
       if (linkedPr) {
         item._pr = linkedPr.id;
         item._prUrl = linkedPr.url;
@@ -1925,6 +1938,10 @@ function getProjectGitStatus(localPath, configuredMainBranch = null) {
   const key = _projectGitStatusCacheKey(localPath, configuredMainBranch);
   const now = Date.now();
   const cached = _projectGitStatusCache.get(key);
+  // Compute ref-mtime freshness once. Used twice below: to gate the TTL
+  // fast-path AND to decide whether the stale-while-revalidate return
+  // should null out the known-stale ahead/behind counters (#2848).
+  const refsAdvanced = !!(cached && _projectGitRefsAdvancedSince(localPath, configuredMainBranch, cached.refMtimes));
   // Within TTL: short-circuit ONLY when no tracked git ref has advanced
   // past cached.ts. Without the mtime gate, a freshly-pulled repo serves
   // the pre-pull ahead/behind counts for up to 15s + one SPA poll (~19s
@@ -1939,7 +1956,7 @@ function getProjectGitStatus(localPath, configuredMainBranch = null) {
   if (cachedIsMissing && fs.existsSync(localPath)) {
     // Path came back — fall through to schedule a fresh probe.
   } else if (cached && cached.ts && (now - cached.ts) < PROJECT_GIT_STATUS_TTL
-      && !_projectGitRefsAdvancedSince(localPath, configuredMainBranch, cached.refMtimes)) {
+      && !refsAdvanced) {
     return cached.value;
   }
   // Cheap synchronous existsSync — short-circuits a path that just disappeared
@@ -1955,7 +1972,22 @@ function getProjectGitStatus(localPath, configuredMainBranch = null) {
   // previous value (or pending placeholder on the very first call). The next
   // /api/status response after the refresh settles will have fresh data.
   _scheduleProjectGitStatusRefresh(localPath, key, configuredMainBranch);
-  return cached ? cached.value : PROJECT_GIT_STATUS_PENDING;
+  if (!cached) return PROJECT_GIT_STATUS_PENDING;
+  // When tracked git refs have advanced past the cached snapshot, the
+  // cached ahead/behind counts are known to be stale (e.g. user just ran
+  // `git pull` / `git fetch` and the local checkout is now current).
+  // Returning the cached value as-is would briefly display a misleading
+  // "behind: 8" after the user has already pulled to current — see
+  // yemi33/minions#2848. Null those specific counters so the dashboard
+  // shows a pending state for ahead/behind until the background probe
+  // settles; branch and dirty flags stay valid enough on the cached
+  // value (and update on the next poll once the probe lands). TTL-expiry
+  // fall-throughs (refsAdvanced=false) still return the prior counters
+  // because nothing local has actually changed there.
+  if (refsAdvanced) {
+    return { ...cached.value, ahead: null, behind: null };
+  }
+  return cached.value;
 }
 
 // Force a refresh now and wait for completion. Called from dashboard boot

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2048",
+  "version": "0.1.2050",
   "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"
@@ -23,7 +23,8 @@
     "test:perf": "node test/perf/managed-spawn-load.test.js",
     "test:e2e:accept": "node test/playwright/accept-baseline.js",
     "test:e2e:accept-force": "node test/playwright/accept-baseline.js --force",
-    "test:setup": "npx playwright install chromium"
+    "test:setup": "npx playwright install chromium",
+    "lint": "eslint dashboard/"
   },
   "keywords": [
     "ai",
@@ -65,7 +66,9 @@
     "@azure-devops/mcp": "2.7.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.58.2"
+    "@playwright/test": "^1.58.2",
+    "eslint": "^9.39.4",
+    "eslint-plugin-no-unsanitized": "^4.1.5"
   },
   "publishConfig": {
     "access": "public"

package/playbooks/fix.md

@@ -93,11 +93,21 @@ Do NOT remove the worktree — the engine handles cleanup automatically.
 
 ## Resolve Review Comments
 
-After pushing, respond to each review comment/thread:
-- **If you fixed it**: Reply confirming the fix, then resolve the thread
-- **If the comment was invalid, stale, already addressed, out of scope, or harmful**: Reply with the evidence-backed rationale explaining why no code change was made — leave the thread open for the reviewer to decide
-- **GitHub**: Reply to each review comment, resolve conversations you've fixed
-- **ADO**: Use `az` CLI first to reply to each thread and update status when supported; use ADO MCP only as a fallback when `az` is unavailable or insufficient. Set status to `fixed` or `closed` for fixes; leave `active` for rationale replies
+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`).
+
+Pick the disposition that matches the finding and post the matching reply, then act on the thread:
+
+- **Fixed** → Reply confirming the fix with commit SHA or `file:line` of the change, then resolve the thread.
+- **Satisfied elsewhere** (addressed by another chunk / sibling PR / existing wiring the reviewer missed) → Reply citing the exact PR number, commit SHA, or `file:line` that satisfies it, then resolve. Example: `Satisfied by chunk 6 (PR 5216079) — ArtifactsMainScreen.kt:305 re-fires start() via LaunchedEffect on every screen enter.`
+- **Deferred** (non-blocking nit you accept but choose not to act on now) → Reply starting with `Deferred:` and a one-line reason, then resolve. Example: `Deferred: default-off rollout switch makes this acceptable for v1; revisit if telemetry shows otherwise.`
+- **Tracked as follow-up** → Reply with `Tracked as follow-up: W-…` and the WI link, then resolve (see `## Follow-up Dispatch` below).
+- **Won't fix / disagree** (comment is invalid, stale, already addressed, out of scope, or harmful) → Reply with the evidence-backed rationale explaining why no code change was made. Leave the thread **active** for the reviewer to decide; do NOT resolve unilaterally.
+
+Host-specific mechanics:
+- **GitHub**: Reply to each review comment, then resolve the conversation for the four resolve-eligible dispositions above. Leave Won't-fix threads unresolved.
+- **ADO**: Use `az` CLI first to reply to each thread and update status when supported; use ADO MCP only as a fallback when `az` is unavailable or insufficient. Set status to `fixed` for Fixed/Satisfied-elsewhere/Tracked-as-follow-up and `closed` for Deferred; leave `active` for Won't-fix rationale replies.
+
+Hard rule: never resolve, close, or mark-fixed a thread without first posting a reply that explains the disposition. The chunk-5 / Caleb-Tseng / MaiLibraryViewModel thread (ADO 5215549 thread 65692221) is the canonical bad example — closed silently with no audit trail.
 
 ## Follow-up Dispatch
 

package/playbooks/shared-rules.md

@@ -140,6 +140,35 @@ Concretely:
 - If you skipped local validation, say so in the completion JSON (e.g. `tests: skipped — relying on PR pipeline`) and still exit.
 - Holding a slot to watch a pipeline is wasted capacity; the engine has its own pipeline-monitoring path.
 
+## Resolving Review Threads — No Silent Closures
+
+Whenever you resolve, close, or mark-fixed any PR review thread (GitHub
+conversation or ADO thread), you MUST first post a reply on that thread
+explaining the disposition. This is non-negotiable across every playbook
+(`fix`, `review`, `implement`, follow-up dispatch, anything that touches
+a review thread).
+
+Allowed dispositions and what the reply MUST contain:
+- **Fixed** → reply with commit SHA or file:line of the change, then resolve.
+- **Satisfied elsewhere** (addressed by another chunk / sibling PR / existing
+  wiring the reviewer missed) → reply citing the exact PR number, commit
+  SHA, or `file:line` that satisfies it, then resolve. Example:
+  `Satisfied by chunk 6 (PR 5216079) — ArtifactsMainScreen.kt:305
+  re-fires start() via LaunchedEffect on every screen enter.`
+- **Deferred** (non-blocking nit you accept but choose not to act on now)
+  → reply starting with `Deferred:` and a one-line reason, then resolve.
+  Example: `Deferred: default-off rollout switch makes this acceptable
+  for v1; revisit if telemetry shows otherwise.`
+- **Tracked as follow-up** → reply with `Tracked as follow-up: W-…` and
+  the WI link, then resolve (see follow-up dispatch template).
+- **Won't fix / disagree** → reply with the evidence-backed rationale;
+  leave the thread **active** for the reviewer to decide. Do NOT resolve
+  unilaterally.
+
+Hard rule: resolving a thread with no reply comment is a process violation.
+The chunk-5 / Caleb-Tseng / MaiLibraryViewModel thread (ADO 5215549 thread
+65692221) is the canonical bad example — closed silently with no audit trail.
+
 {{#github_shared_rules}}
 ## Checking PR and Build Status