@yemi33/minions 0.1.2320 → 0.1.2322

package/dashboard/docs/typography.md

@@ -41,7 +41,7 @@ two stay in lockstep.
 | Token              | Value | Common use                                                |
 | ------------------ | ----- | --------------------------------------------------------- |
 | `--text-xs`        | 10px  | Smallest legitimate text; sidebar badges, count pills     |
-| `--text-sm`        | 11px  | Status badges, chip / tag labels                          |
+| `--text-sm`        | 12px  | Status badges, chip / tag labels                          |
 | `--text-base`      | 12px  | Captions, secondary metadata, dense table cells           |
 | `--text-md`        | 13px  | Default for slim chat / detail tables / button labels     |
 | `--text-lg`        | 14px  | Body text, modal textarea, card titles                    |
@@ -57,6 +57,25 @@ two stay in lockstep.
 > token that breaks the "all px" rule and is explicitly allowlisted in
 > the tripwire.
 
+### 12px readability floor (W-mr3xgejt0008d3a5)
+
+`--text-sm` was raised from an 11px base to **12px** so it clears the 12px
+readability floor in both stylesheets: classic renders it at `12 × 1.05 =
+12.6px`, slim at `12 × 1 = 12px`. `--text-xs` (10px base) stays below the
+floor and is reserved for the very smallest chrome. To lift the
+highest-signal small-text callsites off `--text-xs`, these selectors were
+reassigned to `--text-sm`:
+
+- `.sidebar-count` — primary nav count pill
+- `.dispatch-stuck` — uppercase red "stuck" status badge
+- `.pl-node-meta` — muted plan-node secondary text
+- `.error-details-btn` — uppercase error-details button label
+
+The `--text-sm` selectors already on the token (`.table th`, `.pr-table th`,
+`.token-agent-table th`, `.status-badge`, `.sidebar-link`, slim
+`.tile-item-subtle`) now clear the floor automatically via the token bump —
+no per-callsite change needed.
+
 ## Role aliases (preferred for new code)
 
 Use the role token when adding new UI. It survives a future size-scale
@@ -70,7 +89,7 @@ redesign without callsite edits.
 | `--text-body`          | `--text-lg` (14px)  | Default body text, paragraphs             |
 | `--text-meta`          | `--text-md` (13px)  | Captions, timestamps, secondary metadata  |
 | `--text-caption`       | `--text-base` (12px)| Small labels, table cells                 |
-| `--text-micro`         | `--text-sm` (11px)  | Chip / tag pill labels                    |
+| `--text-micro`         | `--text-sm` (12px)  | Chip / tag pill labels                    |
 | `--text-code`          | (`0.9em`)           | Inline code                               |
 
 ## Utility classes

package/dashboard/js/render-prs.js

@@ -49,8 +49,14 @@ async function fetchPullRequestsFromDisk(projects) {
       out.push(pr);
     }
   }
-  // Same sort the engine applies: most recent created first, fall back to id.
+  // Same sort the engine applies (engine/queries.js#getPullRequests): group
+  // terminal (merged/abandoned/closed) PRs to the bottom, then most recent
+  // created first within each group, falling back to id.
+  const _isTerminalPr = (pr) => pr.status === 'merged' || pr.status === 'abandoned' || pr.status === 'closed';
   out.sort((a, b) => {
+    const at = _isTerminalPr(a) ? 1 : 0;
+    const bt = _isTerminalPr(b) ? 1 : 0;
+    if (at !== bt) return at - bt;
     const ac = a.created || '';
     const bc = b.created || '';
     if (ac && bc) return bc.localeCompare(ac);
@@ -264,15 +270,23 @@ function prRow(pr) {
   // ellipsis-truncated content reveals the full text. Cell tags stay bare so
   // the header-to-cell count assertion in test/unit.test.js continues to
   // balance.
+  // First-column secondary project label (W-mr3mowg9) — mirrors the pr-desc
+  // secondary-text pattern used in the Title cell so reviewers can see at a
+  // glance which project a PR belongs to. `_project` is stamped by the engine
+  // enrichment / getAllPrs stamping (see top-of-file note + line ~33).
+  const projectName = pr._project ? String(pr._project) : '';
+  const projectLabelHtml = projectName
+    ? '<div class="pr-desc pr-id-project" title="' + escapeHtml(projectName) + '">' + escapeHtml(projectName) + '</div>'
+    : '';
   return '<tr>' +
-    '<td><span class="pr-id" title="' + escapeHtml(String(prId)) + '">' + escapeHtml(prShortId(String(prId))) + '</span></td>' +
+    '<td><span class="pr-id" title="' + escapeHtml(String(prId)) + '">' + escapeHtml(prShortId(String(prId))) + '</span>' + projectLabelHtml + '</td>' +
     '<td><a class="pr-title" title="' + escapeHtml(titleText) + '" href="' + escapeHtml(safeUrl(url)) + '" target="_blank" rel="noopener">' + escapeHtml(titleText) + '</a>' + followupChip + pausedChips + (descPreview ? '<div class="pr-desc" title="' + escapeHtml(descPreview) + '">' + escapeHtml(descPreview.length > 120 ? descPreview.slice(0, 120) + '...' : descPreview) + '</div>' : '') + '</td>' +
-    '<td><span class="pr-agent" title="' + escapeHtml(agentText) + '">' + escapeHtml(agentText) + '</span></td>' +
-    '<td><span class="' + branchClass + '" title="' + escapeHtml(branchError || branchLabel) + '">' + escapeHtml(branchLabel) + '</span>' + pendingReasonHtml + '</td>' +
+    '<td><span class="pr-badge ' + statusClass + '" title="' + escapeHtml(statusLabel) + '">' + escapeHtml(statusLabel) + '</span></td>' +
     '<td><span class="pr-badge ' + reviewClass + '" title="' + escapeHtml(reviewTitle || reviewLabel) + '">' + escapeHtml(reviewLabel) + '</span></td>' +
+    '<td><span class="' + branchClass + '" title="' + escapeHtml(branchError || branchLabel) + '">' + escapeHtml(branchLabel) + '</span>' + pendingReasonHtml + '</td>' +
+    '<td><span class="pr-agent" title="' + escapeHtml(agentText) + '">' + escapeHtml(agentText) + '</span></td>' +
     '<td>' + reviewerCell + '</td>' +
     '<td><span class="pr-badge ' + buildClass + '" title="' + escapeHtml(buildTitle || buildLabel) + '">' + escapeHtml(buildLabel) + '</span></td>' +
-    '<td><span class="pr-badge ' + statusClass + '" title="' + escapeHtml(statusLabel) + '">' + escapeHtml(statusLabel) + '</span></td>' +
     '<td>' + (observeBtn || '<span style="color:var(--muted);font-size:var(--text-base)">—</span>') + '</td>' +
     '<td><span class="pr-date" title="' + escapeHtml(createdLabel) + '">' + escapeHtml(createdLabel) + '</span></td>' +
     '<td><button class="pr-info-pill" data-pr-id="' + escapeHtml(String(prId)) + '" onclick="event.stopPropagation();openPrDetail(this.dataset.prId)" title="Open PR detail (in-stack modal)">&#x2197;</button>' +
@@ -286,14 +300,14 @@ function prRow(pr) {
 // the viewport (sticky scrollbar — see styles.css).
 const PRS_COLGROUP =
   '<colgroup>' +
-    '<col style="width:110px">' +   // PR id (short label: `gh #481` / `ado #5383607`)
+    '<col style="width:130px">' +   // PR id (short label: `gh #481` / `ado #5383607`) + project label
     '<col style="width:320px">' +   // Title
-    '<col style="width:140px">' +   // Agent
-    '<col style="width:200px">' +   // Branch
+    '<col style="width:110px">' +   // Status
     '<col style="width:130px">' +   // Review
+    '<col style="width:200px">' +   // Branch
+    '<col style="width:140px">' +   // Agent
     '<col style="width:140px">' +   // Signed Off By
     '<col style="width:130px">' +   // Build
-    '<col style="width:110px">' +   // Status
     '<col style="width:100px">' +   // Observe
     '<col style="width:130px">' +   // Created
     '<col style="width:80px">' +    // Actions (info-pill + remove)
@@ -303,7 +317,7 @@ function prTableHtml(rows) {
   return '<div class="pr-table-wrap pr-table-wrap--prs"><table class="pr-table pr-table--prs">' +
     PRS_COLGROUP +
     '<thead><tr>' +
-    '<th>PR</th><th>Title</th><th>Agent</th><th>Branch</th><th>Review</th><th>Signed Off By</th><th>Build</th><th>Status</th><th>Observe</th><th>Created</th><th></th>' +
+    '<th>PR</th><th>Title</th><th>Status</th><th>Review</th><th>Branch</th><th>Agent</th><th>Signed Off By</th><th>Build</th><th>Observe</th><th>Created</th><th></th>' +
     '</tr></thead><tbody>' + rows + '</tbody></table></div>';
 }
 

package/dashboard/slim/styles.css

@@ -42,7 +42,7 @@
          the slim UI at its current text size — the global bump is excluded
          here by design. Do NOT raise this value to match main. */
       --minions-text-scale: 1;
-      --text-xs: calc(10px * var(--minions-text-scale)); --text-sm: calc(11px * var(--minions-text-scale)); --text-base: calc(12px * var(--minions-text-scale));
+      --text-xs: calc(10px * var(--minions-text-scale)); --text-sm: calc(12px * var(--minions-text-scale)); --text-base: calc(12px * var(--minions-text-scale));
       --text-md: calc(13px * var(--minions-text-scale)); --text-lg: calc(14px * var(--minions-text-scale)); --text-xl: calc(16px * var(--minions-text-scale)); --text-2xl: calc(18px * var(--minions-text-scale));
       --text-stat: calc(22px * var(--minions-text-scale)); --text-stat-lg: calc(28px * var(--minions-text-scale)); --text-display: calc(32px * var(--minions-text-scale));
       --text-role-display:    var(--text-display);

package/dashboard/styles.css

@@ -28,7 +28,7 @@
        its own (un-scaled) factor of 1, so the slim UI is excluded from the
        bump by construction. */
     --minions-text-scale: 1.05;
-    --text-xs: calc(10px * var(--minions-text-scale)); --text-sm: calc(11px * var(--minions-text-scale)); --text-base: calc(12px * var(--minions-text-scale));
+    --text-xs: calc(10px * var(--minions-text-scale)); --text-sm: calc(12px * var(--minions-text-scale)); --text-base: calc(12px * var(--minions-text-scale));
     --text-md: calc(13px * var(--minions-text-scale)); --text-lg: calc(14px * var(--minions-text-scale)); --text-xl: calc(16px * var(--minions-text-scale)); --text-2xl: calc(18px * var(--minions-text-scale));
     --text-stat: calc(22px * var(--minions-text-scale)); --text-stat-lg: calc(28px * var(--minions-text-scale)); --text-display: calc(32px * var(--minions-text-scale));
 
@@ -45,7 +45,7 @@
     --text-body:            var(--text-lg);       /* 14px — default body text */
     --text-meta:            var(--text-md);       /* 13px — captions, timestamps, secondary metadata */
     --text-caption:         var(--text-base);     /* 12px — small labels, table cells */
-    --text-micro:           var(--text-sm);       /* 11px — chip / tag pill labels */
+    --text-micro:           var(--text-sm);       /* 12px — chip / tag pill labels */
     --text-code:            0.9em;                /* inline code; relative so it scales with the surrounding text */
 
     /* Border radius */
@@ -107,7 +107,7 @@
   .sidebar-link .notif-badge.done { top: 50%; right: 6px; transform: translateY(-50%); width: 6px; height: 6px; }
   .sidebar-link:hover { color: var(--text); background: var(--surface2); }
   .sidebar-link.active { color: var(--blue); border-left-color: var(--blue); background: var(--surface2); font-weight: 600; }
-  .sidebar-count { font-size: var(--text-xs); color: var(--muted); background: var(--surface2); padding: 1px 5px; border-radius: 8px; min-width: 16px; text-align: center; }
+  .sidebar-count { font-size: var(--text-sm); color: var(--muted); background: var(--surface2); padding: 1px 5px; border-radius: 8px; min-width: 16px; text-align: center; }
   .page-content { flex: 1; overflow-y: auto; min-width: 0; }
   .page { display: none; }
   .page.active { display: block; }
@@ -264,7 +264,7 @@
   .pl-node-box.condition { border-style: dashed; }
   .pl-node-box.pl-node-stop { border-style: dotted; border-color: var(--muted); opacity: 0.7; }
   .pl-node-arrow { display: flex; align-items: center; padding: 0 2px; color: var(--muted); font-size: var(--text-md); flex-shrink: 0; margin-top: 8px; }
-  .pl-node-meta { font-size: var(--text-xs); color: var(--muted); margin-top: 2px; text-align: center; max-width: 120px; overflow: hidden; text-overflow: ellipsis; }
+  .pl-node-meta { font-size: var(--text-sm); color: var(--muted); margin-top: 2px; text-align: center; max-width: 120px; overflow: hidden; text-overflow: ellipsis; }
   .pl-node-loop { font-size: var(--text-sm); color: var(--muted); margin-top: 6px; display: flex; align-items: center; gap: 6px; }
   .pipeline-card { background: var(--surface); border: 1px solid var(--border); border-radius: var(--radius-lg); padding: 12px 16px; margin-bottom: var(--space-4); cursor: pointer; transition: border-color var(--transition-fast), transform var(--transition-fast); }
   .pipeline-card:hover { border-color: var(--blue); transform: translateY(-1px); }
@@ -358,6 +358,7 @@
   .pr-title:hover { text-decoration: underline; }
   .pr-desc { color: var(--muted); font-size: var(--text-sm); font-weight: 400; margin-top: 2px; line-height: 1.4; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 400px; }
   .pr-id { color: var(--muted); font-family: Consolas, monospace; font-size: var(--text-base); }
+  .pr-id-project { max-width: 120px; font-size: var(--text-xs); }
   .pr-agent { font-size: var(--text-base); color: var(--text); }
   .pr-branch { display: inline-block; max-width: 280px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; vertical-align: middle; font-family: Consolas, monospace; font-size: var(--text-sm); color: var(--muted); background: var(--bg); padding: var(--space-1) var(--space-3); border-radius: 3px; border: 1px solid var(--border); }
   .pr-branch.branch-missing { color: var(--red); border-color: var(--red); background: rgba(248,81,73,0.12); }
@@ -377,7 +378,7 @@
   .pr-badge.build-escalated { background: rgba(248,81,73,0.25); color: var(--red); border: 2px solid var(--red); font-weight: 600; }
   /* W-mq08kuog001110a6 — Needs-Attention chip for stuck pending work items. */
   .pr-badge.needs-attention { background: rgba(210,153,34,0.15); color: var(--yellow); border: 1px solid var(--yellow); font-weight: 600; cursor: help; }
-  .error-details-btn { font-size: var(--text-xs); padding: var(--space-1) var(--space-3); margin-left: var(--space-2); background: rgba(248,81,73,0.15); color: var(--red); border: 1px solid var(--red); border-radius: var(--radius-lg); cursor: pointer; font-weight: 600; text-transform: uppercase; letter-spacing: 0.3px; }
+  .error-details-btn { font-size: var(--text-sm); padding: var(--space-1) var(--space-3); margin-left: var(--space-2); background: rgba(248,81,73,0.15); color: var(--red); border: 1px solid var(--red); border-radius: var(--radius-lg); cursor: pointer; font-weight: 600; text-transform: uppercase; letter-spacing: 0.3px; }
   .error-details-btn:hover { background: rgba(248,81,73,0.3); }
   .pr-empty { color: var(--muted); font-style: italic; font-size: var(--text-md); padding: var(--space-6) 0; }
   .pr-pager { display: flex; align-items: center; justify-content: space-between; margin-top: 10px; }
@@ -670,7 +671,8 @@
      in render-other.js, but with a dashed border + green text to read as
      a placeholder/call-to-action. */
   .empty-state-add {
-    display: inline-block;
+    display: inline-flex; align-items: center; justify-content: center;
+    min-height: 24px; min-width: 24px;
     background: var(--surface2);
     border: 1px dashed var(--border);
     color: var(--green);
@@ -786,7 +788,15 @@
   .cmd-chip.priority-medium { color: var(--yellow); border-color: rgba(210,153,34,0.3); background: rgba(210,153,34,0.08); }
   .cmd-chip.priority-low { color: var(--muted); }
   .cmd-chip.project-chip { color: var(--green); border-color: rgba(63,185,80,0.3); background: rgba(63,185,80,0.08); }
-  .cmd-chip .chip-x { cursor: pointer; opacity: 0.5; margin-left: 2px; font-size: var(--text-lg); }
+  /* Close/remove affordance on command chips. Sized as a >=24x24px hit target
+     (W-mr3xgo9a a11y sweep) via inline-flex box + min dimensions rather than
+     relying on the bare glyph; the glyph stays centered. Negative vertical
+     margins keep the enlarged tap box from inflating the parent chip's height. */
+  .cmd-chip .chip-x {
+    display: inline-flex; align-items: center; justify-content: center;
+    min-width: 24px; min-height: 24px; margin: -4px -4px -4px 2px;
+    cursor: pointer; opacity: 0.5; font-size: var(--text-lg);
+  }
   .cmd-chip .chip-x:hover { opacity: 1; }
   .cmd-chip select {
     background: transparent; border: none; color: inherit; font-size: var(--text-base);
@@ -978,7 +988,7 @@
   .dispatch-agent { font-weight: 600; color: var(--text); }
   .dispatch-task { flex: 1; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
   .dispatch-time { font-size: var(--text-sm); color: var(--border); }
-  .dispatch-stuck { font-size: var(--text-xs); font-weight: 700; padding: var(--space-1) var(--space-3); border-radius: var(--radius-sm); text-transform: uppercase; letter-spacing: 0.3px; background: rgba(248,81,73,0.18); color: var(--red); border: 1px dashed var(--red); margin-left: var(--space-2); animation: pulse 1.5s infinite; cursor: help; }
+  .dispatch-stuck { font-size: var(--text-sm); font-weight: 700; padding: var(--space-1) var(--space-3); border-radius: var(--radius-sm); text-transform: uppercase; letter-spacing: 0.3px; background: rgba(248,81,73,0.18); color: var(--red); border: 1px dashed var(--red); margin-left: var(--space-2); animation: pulse 1.5s infinite; cursor: help; }
 
   /* Engine Log */
   .log-list { max-height: 280px; overflow-y: auto; display: flex; flex-direction: column; gap: var(--space-1); }

package/dashboard.js

@@ -13767,11 +13767,16 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         // routes the changes through an isolated worktree (so nothing is ever
         // committed in the operator's live main). See engine/create-pr-worktree.js.
         const checkoutMode = shared.resolveCheckoutMode(project);
+        // Resolve the project's actual main/base branch instead of trusting
+        // whatever `git rev-parse --abbrev-ref HEAD` returned as a safe base —
+        // the live checkout may be sitting on a stale/topic branch whose
+        // unrelated commits would otherwise leak into the new PR (W-mr3jbpru).
+        const mainBranch = shared.resolveMainBranch(project.localPath, project.mainBranch);
         const followups = hasChanges
-          ? prAction.buildCreatePrFollowups({ project: projectName, branch, contextOnly: !!body?.contextOnly, checkoutMode })
+          ? prAction.buildCreatePrFollowups({ project: projectName, branch, contextOnly: !!body?.contextOnly, checkoutMode, mainBranch })
           : [];
         recordCcTurnIfPresent(req, { kind: 'pr-action', id: '', title: `offer create-pr (${projectName})`, project: projectName, followups });
-        return jsonReply(res, 200, { ok: true, hasChanges, branch, changedFileCount, checkoutMode, followups }, req);
+        return jsonReply(res, 200, { ok: true, hasChanges, branch, changedFileCount, checkoutMode, mainBranch, followups }, req);
       } catch (e) {
         return jsonReply(res, e.statusCode || 400, { error: e.message }, req);
       }

package/docs/harness-transparency.md

@@ -62,6 +62,21 @@ flagged un-grounded downstream. This capture is observability only — it does
 **not** change which dirs are propagated at spawn time, and any failure here is
 non-fatal (the spawn proceeds).
 
+**Monorepo sub-project contributes `--add-dir` roots (P-f52d81ba).** The `addDirs` set
+folded into the manifest includes the project-local harness dirs propagated for
+the dispatch. When the engine auto-derives a dominant sub-project (see
+[project-skills.md → Monorepo sub-project scoping](project-skills.md#monorepo-sub-project-scoping)),
+those sub-project-scoped `--project-harness-dir` roots flow into `propagatedProjectHarnessDirs`
+→ `addDirs` → the `_harnessPropagated` manifest. The clip that selects them is
+the **same** `shared.filterProjectHarnessDirsForWorkdir` used for an explicit
+`meta.workdir` — `spawnAgent` passes `workdir: validatedWorkdir || _effectiveSubproject
+|| null`, so an explicit `meta.workdir` wins, else the auto-derived sub-project's
+first-level segment clips the surface, else no clip (whole-project harness).
+Because the manifest captures the same sub-project-clipped roots the agent was actually
+handed, a self-reported skill usage against a sub-project's skill (e.g.
+`ocm/.claude/skills/…`) still grounds `true` — grounding stays faithful under
+sub-project scoping instead of falsely flagging the sub-project's own skills.
+
 The grounding cross-check (P-c6f5e8b3) runs in `engine/lifecycle.js`
 `runPostCompletionHooks` once the completion report is parsed and nonce-trusted:
 `shared.groundHarnessUsed(completionReport.harnessUsed, _harnessPropagated)`
@@ -170,7 +185,8 @@ evaluation pass) can see what tooling drove a dispatch:
 ## Related
 
 - `engine/shared.js` — `HARNESS_USED_KINDS`, `HARNESS_USED_MAX_ENTRIES`,
-  `HARNESS_USED_MAX_FIELD_LEN`, `normalizeHarnessUsed()`, `groundHarnessUsed()`
+  `HARNESS_USED_MAX_FIELD_LEN`, `normalizeHarnessUsed()`, `groundHarnessUsed()`,
+  `filterProjectHarnessDirsForWorkdir()` (the sub-project/workdir clip)
 - `engine/queries.js` — `buildHarnessPropagatedManifest()`,
   `getUserHarnesses()`, `getProjectHarnesses()`
 - `engine/lifecycle.js` — `resolveHarnessPropagated()` + the grounding

package/docs/live-checkout-mode.md

@@ -136,6 +136,21 @@ Live-mode agents run **in-place** in the operator's checkout, so when a dispatch
 
 The core invariant holds end-to-end through restore: **the engine only ever switches branches — it never `git reset`s, `git clean`s, or `git stash`es the operator's tree, and never passes `--force`.** The one addition — the self-healing auto-commit — only ever runs `git add`/`git commit` on the engine's *own* agent branch, never on operator refs, and never discards.
 
+## Create-PR chip safety (CC-initiated, separate from the dispatch path)
+
+The Command Center **"Create PR"** chip (`dashboard.js` → `POST /api/pr-action/offer-create-pr` → `engine/pr-action.js#buildCreatePrFollowups`) is a **separate, ad-hoc path** that opens a PR for a local edit Command Center just made in a live-checkout project. It does **not** go through `prepareLiveCheckout`, so the dirty-tree / orphaned-branch / mid-operation defenses above (Guarantees 2 & 5, dispatch-start self-heal) do **not** apply to it. This path needs its own equivalent safety contract, because it shares the same failure mode: the live checkout may be sitting on a stale/topic branch left over from a previous run, a manually-checked-out branch, or any other non-main state.
+
+**The bug it fixes (W-mr3jbpru).** The old live-mode chip message keyed its branch instruction off `git rev-parse --abbrev-ref HEAD` (the *current* branch) and only told the agent to branch off cleanly **if** that current branch already happened to be the project's main branch. If the checkout was on any other branch, the message told the agent to commit the new changes **directly onto that branch** — silently carrying all of that branch's unrelated commits into the new PR. There was no engine-side verification that the current branch was clean or at parity with main; it was trusted blindly. A user hit exactly this: a Create-PR chip PR ended up built on top of a leftover topic branch and carried unrelated diffs.
+
+**The contract now (unconditional, current-branch never trusted as base).**
+
+1. The handler resolves the project's **actual** main/base branch with `shared.resolveMainBranch(project.localPath, project.mainBranch)` — it does **not** trust `git rev-parse --abbrev-ref HEAD` as a safe base — and threads it to `buildCreatePrFollowups({ …, mainBranch })`.
+2. The CC-facing message is **unconditional**: regardless of what is currently checked out, it instructs the agent to build the PR on a **fresh branch off the up-to-date `origin/<mainBranch>` tip**, via `git stash push --include-untracked` → `git fetch origin <mainBranch>` → `git checkout -B <new-well-named-branch> origin/<mainBranch>` → `git stash pop` → commit → push → open the PR against `<mainBranch>` → link via `/api/pull-requests/link` → **switch the working tree back to the original branch** it started on (the same restore step the old message had). The old `if <current-branch> is the project's default/main branch` conditional is gone entirely.
+3. If `git stash pop` reports a merge conflict (the stashed diff doesn't cleanly apply onto the fresh main tip), the message instructs the agent to **stop and surface the conflict** to the user rather than force-resolving it silently.
+4. The message **names the resolved main branch explicitly** (e.g. `origin/android`) instead of leaving "the project main branch" vague, so the always-branch-off-resolved-main rule is stated unambiguously.
+
+This mirrors, in CC-instruction form, what `prepareLiveCheckout` enforces engine-side for the dispatch path: never reuse whatever branch the live checkout happened to be on as the base for new work. The **worktree-mode** branch of `buildCreatePrFollowups` is unaffected — that path already routes the changes through an isolated worktree (`engine/create-pr-worktree.js`) so nothing is ever committed on the operator's `main`.
+
 ## Operator workflow
 
 ### Enabling live mode (dashboard)
@@ -253,6 +268,7 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | `engine.js` — worktree-pool / orphan-GC short-circuits | `worktreePath===null` no-ops in live mode (P-a3f9b206). |
 | `engine/cleanup.js` — `runPeriodicWorktreeSweep` live filter | Excludes live-checkout projects from the registry-derived periodic worktree GC so the operator's primary checkout never enters the GC decision surface (PL-live-checkout-reliability-hardening). |
 | `engine/create-pr-worktree.js` — `prepareCreatePrWorktree` step-4 restore | `reset --hard HEAD` (not the index-leaking `checkout -- .`) + retried untracked removal + `liveTreeDirty` surfaced + `shared.removeWorktree` teardown (PL-live-checkout-reliability-hardening). |
+| `engine/pr-action.js` — `buildCreatePrFollowups({ …, mainBranch })` live-mode message | CC "Create PR" chip instruction. In live mode the PR is ALWAYS built on a fresh branch off `origin/<mainBranch>` (stash → fetch → `checkout -B` → pop → commit → push → PR → restore), never reusing the current branch as the base; stop-on-stash-pop-conflict. `dashboard.js` `POST /api/pr-action/offer-create-pr` resolves `mainBranch` via `shared.resolveMainBranch` and threads it in (W-mr3jbpru). |
 | `dashboard/js/settings.js` — checkoutMode dropdown + chip + `set-liveCheckoutAutoReset` fleet toggle | Operator-facing UI; the fleet-wide auto-reset toggle persists to `engine.liveCheckoutAutoReset` (per-project UI deferred — config.json only) (P-a3f9b207; auto-reset toggle W-mqvejug6000eeb20). |
 | `test/unit/{resolve-spawn-paths-live-mode,prepare-live-checkout,spawn-agent-live-mode-wiring,live-checkout-auto-stash}.test.js` | Wiring and contract tests (P-a3f9b208; auto-stash helpers W-mqtvnnj1000357fa). |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` | Non-retryable refusal class. |

package/docs/project-skills.md

@@ -46,6 +46,67 @@ The walk is **cheap and bounded** — preserve every guardrail in
 - ≤ 50 nested areas probed
 - Missing worktree / unreadable → `[]` (never throws)
 
+## Monorepo sub-project scoping
+
+P-f52d81ba. In a monorepo, a dispatch usually touches one sub-project (`ocm/`,
+`loop/`, `officemobile/`, …) even though discovery walks every sub-project's
+`.claude/skills`. Scoping surfaces that sub-project's skills **first** without hiding
+the rest, so an `ocm/`-focused agent isn't forced to scroll past `loop/` tooling
+to find the relevant pack.
+
+**Changed-path → sub-project detection.** `detectDominantSubproject({ projectPath,
+changedPaths })` (engine/discover-project-skills.js) counts the changed paths
+per first-level directory, keyed on the POSIX first segment. It reuses
+`_listAreas` for the authoritative set of valid sub-projects, so a stray first segment
+that isn't a real top-level dir never counts. It returns `{ subproject, matched,
+total, confident }`. The engine feeds it changed paths from:
+
+- **spawnAgent** (async, authoritative): `git diff --name-only <mainBranch>...HEAD`
+  in the current dispatch's worktree — never a parent/follow-up's stale diff.
+- **renderProjectWorkItemPromptForAgent** (`_deriveDominantSubprojectSync`, build-time
+  fallback with no git access): the work item's `references[*].path`.
+
+**Dominant-sub-project plurality threshold.** `detectDominantSubproject` only reports a sub-project
+as `confident` when the top sub-project holds **≥ 60%** of the sub-project-matched files **and**
+**≥ 2** files (`dominantSubprojectMinRatio` / `dominantSubprojectMinFiles` in `DEFAULTS`,
+overridable via `opts`). Ties break alphabetically for determinism. An empty,
+mixed, or no-known-sub-project diff returns `{ subproject: null, confident: false }` →
+flat discovery (today's global name-sort). This is deliberately conservative:
+a weakly-dominant or split diff falls back to flat surfacing rather than
+mis-scoping to the wrong sub-project.
+
+**Explicit `meta.workdir` wins over auto-detection.** When the operator declares
+`meta.workdir` on the work item, the effective sub-project is its first path segment —
+no diff work is done. Auto-detection only runs when `meta.workdir` is absent.
+The async git-diff-derived sub-project (threaded into the shared-branch re-render via
+`options.dominantSubproject`) overrides the sync `references`-derived guess.
+
+**Prioritized, not exclusive, surfacing.** The effective sub-project is threaded through
+`playbook.js` as `scopeSubproject` into `discoverProjectSkillsWithDiagnostics`. When
+set, entries under `<scopeSubproject>/` lead the list (name-sorted within the group),
+then root-level entries, then other-sub-project entries. **Discovery still walks
+everything — no skills are dropped; only ordering changes.** An empty/unset
+`scopeSubproject` reduces byte-for-byte to the historical global name-then-path sort.
+
+**Configurable per-surface cap.** `ENGINE_DEFAULTS.projectSkillMaxFilesPerSurface`
+(default **200**) caps how many skill packs / command files are read per surface
+(root `.claude/skills`, each `<area>/.claude/skills`, …). `playbook.js` threads
+it into the discovery `opts`; when no override is supplied the module falls back
+to its own `DEFAULTS.maxFilesPerSurface` (50). It's raised well above the
+fallback so large monorepo sub-projects (e.g. an `ocm/.claude/skills` with ~80 packs)
+don't silently drop the most-relevant skills. Entries are alphabetically sorted
+**before** the cap is applied, so the surviving subset is deterministic across
+runs and OSes rather than FS-readdir-order-dependent.
+
+**Truncation diagnostics.** `discoverProjectSkillsWithDiagnostics` returns
+`{ entries, truncations }` where each truncation is `{ surface, dir, scanned,
+total }` — recorded when a surface's `total` file count exceeds `scanned`
+(i.e. the cap dropped entries). `playbook.js` logs a `warn` when any surface
+truncates and stashes the diagnostics so `spawnAgent` can persist the detected
+sub-project (`_dominantSubproject`) and truncations (`_skillDiscoveryTruncations`) onto the
+dispatch record for later grounding/observability. Overflow is thus **observable**
+instead of silent.
+
 ## The intent vocabulary (CLOSED)
 
 | Intent | What belongs here |

package/engine/discover-project-skills.js

@@ -62,6 +62,8 @@ const DEFAULTS = {
   docsScanMaxBytes: 32 * 1024, // CLAUDE.md / copilot-instructions.md top window
   walltimeMs: 250,           // bail rather than block dispatch on pathological FS
   maxAreas: 50,              // cap how many <area>/ dirs we'll probe for nested .claude
+  dominantSubprojectMinRatio: 0.6, // detectDominantSubproject: top sub-project must hold >= this share of sub-project-matched files
+  dominantSubprojectMinFiles: 2,   // detectDominantSubproject: top sub-project must have >= this many matched files
 };
 
 // Intent vocabulary — CLOSED. Each entry maps an intent to the keyword/regex
@@ -169,21 +171,44 @@ function classifyIntents({ name = '', description = '', extra = '', explicit = [
   return intents;
 }
 
+// Record that a scanned surface exceeded opts.maxFilesPerSurface so callers can
+// surface an overflow diagnostic instead of silently dropping entries.
+function _recordTruncation(truncations, surface, projectPath, dir, scanned, total) {
+  if (!Array.isArray(truncations)) return;
+  if (total <= scanned) return;
+  truncations.push({
+    surface,
+    dir: path.relative(projectPath, dir).split(path.sep).join('/'),
+    scanned,
+    total,
+  });
+}
+
 // Walk <baseDir>/.claude/skills/*\/SKILL.md
-function _discoverSkillsAt(baseDir, projectPath, opts, deadline, originLabel) {
+function _discoverSkillsAt(baseDir, projectPath, opts, deadline, originLabel, truncations) {
   const out = [];
   const skillsDir = path.join(baseDir, '.claude', 'skills');
   let entries;
   try { entries = fs.readdirSync(skillsDir, { withFileTypes: true }); } catch { return out; }
+  // Stable alphabetical sort by entry name BEFORE applying the
+  // maxFilesPerSurface cap so the surviving subset is deterministic and
+  // reproducible across runs / OSes (raw readdir order is FS-dependent, so
+  // capping pre-sort silently dropped a non-deterministic slice).
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  const cap = opts.maxFilesPerSurface;
   let scanned = 0;
+  let total = 0;
   for (const ent of entries) {
-    if (scanned >= opts.maxFilesPerSurface) break;
     if (_now() > deadline) break;
     if (!ent.isDirectory()) continue;
     const skillPath = path.join(skillsDir, ent.name, 'SKILL.md');
     let stat;
     try { stat = fs.statSync(skillPath); } catch { continue; }
     if (!stat.isFile()) continue;
+    total += 1;
+    // Beyond the cap we still count `total` (for an accurate overflow
+    // diagnostic) but stop reading/emitting entries.
+    if (scanned >= cap) continue;
     scanned += 1;
     const head = _safeReadHead(skillPath, opts.maxBytesPerFile);
     if (!head) continue;
@@ -202,21 +227,28 @@ function _discoverSkillsAt(baseDir, projectPath, opts, deadline, originLabel) {
       _originLabel: originLabel,
     });
   }
+  _recordTruncation(truncations, 'skill', projectPath, skillsDir, scanned, total);
   return out;
 }
 
 // Walk <baseDir>/.claude/commands/*.md
-function _discoverCommandsAt(baseDir, projectPath, opts, deadline, originLabel) {
+function _discoverCommandsAt(baseDir, projectPath, opts, deadline, originLabel, truncations) {
   const out = [];
   const cmdDir = path.join(baseDir, '.claude', 'commands');
   let entries;
   try { entries = fs.readdirSync(cmdDir, { withFileTypes: true }); } catch { return out; }
+  // Stable alphabetical sort by entry name BEFORE applying the
+  // maxFilesPerSurface cap (see _discoverSkillsAt for the determinism rationale).
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  const cap = opts.maxFilesPerSurface;
   let scanned = 0;
+  let total = 0;
   for (const ent of entries) {
-    if (scanned >= opts.maxFilesPerSurface) break;
     if (_now() > deadline) break;
     if (!ent.isFile()) continue;
     if (!/\.md$/i.test(ent.name)) continue;
+    total += 1;
+    if (scanned >= cap) continue;
     scanned += 1;
     const base = ent.name.replace(/\.md$/i, '');
     const cmdPath = path.join(cmdDir, ent.name);
@@ -232,6 +264,7 @@ function _discoverCommandsAt(baseDir, projectPath, opts, deadline, originLabel)
       _originLabel: originLabel,
     });
   }
+  _recordTruncation(truncations, 'command', projectPath, cmdDir, scanned, total);
   return out;
 }
 
@@ -306,25 +339,138 @@ function _listAreas(projectPath, opts, deadline) {
 }
 
 /**
+ * Pure dominant-sub-project (area) detector.
+ *
+ * Given a set of changed paths, decide whether a single first-level project
+ * sub-project (e.g. `ocm/`, `loop/`, `officemobile/`) dominates the diff strongly
+ * enough that skill discovery / harness surfacing should be scoped to it.
+ * Reuses `_listAreas` for the authoritative set of valid sub-projects (sorted,
+ * dot-dir / node_modules filtered, capped at opts.maxAreas) so a stray first
+ * path segment that is NOT a real top-level directory never counts as a sub-project.
+ *
+ * Purity: no engine state, no fs beyond the single `_listAreas` readdir. The
+ * result is fully determined by (projectPath's first-level dirs, changedPaths,
+ * opts) — unit-testable against a fixture.
+ *
+ * @param {object} args
+ * @param {string} args.projectPath — absolute path to the project worktree / checkout
+ * @param {string[]} args.changedPaths — repo-relative changed file paths (any separator)
+ * @param {object} [args.opts] — override thresholds / caps (mostly for tests)
+ * @returns {{subproject:string|null, matched:number, total:number, confident:boolean}}
+ *   total    — count of changed paths considered
+ *   matched  — count of changed paths that fall under a known sub-project
+ *   subproject — the dominant sub-project when `confident`, else null (flat-discovery fallback)
+ *   confident — top sub-project holds >= minRatio of matched files AND >= minFiles files
+ */
+function detectDominantSubproject(args) {
+  const projectPath = args && args.projectPath;
+  const changedPaths = args && args.changedPaths;
+  const opts = Object.assign({}, DEFAULTS, (args && args.opts) || {});
+
+  const total = Array.isArray(changedPaths) ? changedPaths.length : 0;
+  if (!projectPath || typeof projectPath !== 'string' || total === 0) {
+    return { subproject: null, matched: 0, total, confident: false };
+  }
+
+  const deadline = _now() + Math.max(1, opts.walltimeMs);
+  const subprojects = new Set(_listAreas(projectPath, opts, deadline));
+  if (subprojects.size === 0) {
+    return { subproject: null, matched: 0, total, confident: false };
+  }
+
+  // Count changed files per known sub-project, keyed on the normalized first segment.
+  const counts = new Map();
+  let matched = 0;
+  for (const raw of changedPaths) {
+    if (typeof raw !== 'string' || raw.length === 0) continue;
+    // Normalize to POSIX and strip leading ./ and / so the first segment is
+    // the true top-level directory.
+    let p = raw.replace(/\\/g, '/');
+    while (p.startsWith('./')) p = p.slice(2);
+    while (p.startsWith('/')) p = p.slice(1);
+    const seg = p.split('/')[0];
+    if (!seg || !subprojects.has(seg)) continue;
+    matched += 1;
+    counts.set(seg, (counts.get(seg) || 0) + 1);
+  }
+
+  if (matched === 0) {
+    return { subproject: null, matched: 0, total, confident: false };
+  }
+
+  // Dominant sub-project = highest count; ties broken alphabetically for determinism.
+  let topSubproject = null;
+  let topCount = -1;
+  for (const [sub, count] of counts) {
+    if (count > topCount || (count === topCount && (topSubproject === null || sub.localeCompare(topSubproject) < 0))) {
+      topSubproject = sub;
+      topCount = count;
+    }
+  }
+
+  const minRatio = typeof opts.dominantSubprojectMinRatio === 'number' ? opts.dominantSubprojectMinRatio : DEFAULTS.dominantSubprojectMinRatio;
+  const minFiles = typeof opts.dominantSubprojectMinFiles === 'number' ? opts.dominantSubprojectMinFiles : DEFAULTS.dominantSubprojectMinFiles;
+  const confident = topCount >= minFiles && (topCount / matched) >= minRatio;
+
+  return { subproject: confident ? topSubproject : null, matched, total, confident };
+}
+
+// Normalize a caller-supplied scopeSubproject into a bare POSIX first-level dir name
+// (backslashes → slashes, leading/trailing slashes + whitespace stripped).
+// Returns '' when unset/empty so the sort can cheaply skip scope grouping.
+function _normalizeScopeSubproject(scopeSubproject) {
+  if (typeof scopeSubproject !== 'string') return '';
+  return scopeSubproject.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '').trim();
+}
+
+// The project sub-project an entry's (repo-relative POSIX) path lives under, or
+// null for root-level entries. Sub-project skill/command paths look like
+// `<area>/.claude/…`; root skills/commands (`.claude/…`) and root docs
+// (`CLAUDE.md`, `.github/copilot-instructions.md`) have no owning sub-project.
+function _entrySubproject(entryPath) {
+  const m = /^([^/]+)\/\.claude\//.exec(String(entryPath || '').replace(/\\/g, '/'));
+  return m ? m[1] : null;
+}
+
+// Scope-ordering group for a scopeSubproject-aware sort. Lower ranks lead the list:
+//   0 = entry is under <scopeSubproject>/, 1 = root-level, 2 = other-sub-project.
+function _scopeGroup(entryPath, scopeSubproject) {
+  const p = String(entryPath || '').replace(/\\/g, '/');
+  if (scopeSubproject && (p === scopeSubproject || p.startsWith(scopeSubproject + '/'))) return 0;
+  return _entrySubproject(p) === null ? 1 : 2;
+}
+
+/**
+ * Diagnostics-returning discovery. Same walk as discoverProjectSkills but also
+ * reports per-surface overflow records so callers can tell when a directory
+ * exceeded opts.maxFilesPerSurface (and therefore had entries dropped) instead
+ * of silently losing them.
+ *
  * @param {object} args
  * @param {string} args.projectPath — absolute path to the project worktree / checkout
+ * @param {string} [args.scopeSubproject] — when set/non-empty, surface entries under
+ *   `<scopeSubproject>/` FIRST (name-sorted within group), then root-level entries,
+ *   then other-sub-project entries. Discovery still walks everything (no skills
+ *   dropped); only ordering changes. Unset/empty ⇒ today's global name-sort.
  * @param {object} [args.opts] — override defaults (mostly for tests)
- * @returns {Array<{kind:string,name:string,path:string,oneLineDescription:string,intents:string[]}>}
+ * @returns {{entries:Array<{kind:string,name:string,path:string,oneLineDescription:string,intents:string[]}>, truncations:Array<{surface:string,dir:string,scanned:number,total:number}>}}
  */
-function discoverProjectSkills(args) {
+function discoverProjectSkillsWithDiagnostics(args) {
   const projectPath = args && args.projectPath;
-  if (!projectPath || typeof projectPath !== 'string') return [];
-  try { if (!fs.statSync(projectPath).isDirectory()) return []; } catch { return []; }
+  if (!projectPath || typeof projectPath !== 'string') return { entries: [], truncations: [] };
+  try { if (!fs.statSync(projectPath).isDirectory()) return { entries: [], truncations: [] }; } catch { return { entries: [], truncations: [] }; }
 
+  const scopeSubproject = _normalizeScopeSubproject(args.scopeSubproject);
   const opts = Object.assign({}, DEFAULTS, args.opts || {});
   const deadline = _now() + Math.max(1, opts.walltimeMs);
 
   const seenKey = new Set(); // dedupe across surfaces by `${kind}:${name}`
   const seenSlash = new Set();
   const all = [];
+  const truncations = [];
 
   // 1. Root-level skills.
-  for (const entry of _discoverSkillsAt(projectPath, projectPath, opts, deadline, 'root')) {
+  for (const entry of _discoverSkillsAt(projectPath, projectPath, opts, deadline, 'root', truncations)) {
     const key = `skill:${entry.name}`;
     if (seenKey.has(key)) continue;
     seenKey.add(key);
@@ -332,7 +478,7 @@ function discoverProjectSkills(args) {
   }
 
   // 2. Root-level commands.
-  for (const entry of _discoverCommandsAt(projectPath, projectPath, opts, deadline, 'root')) {
+  for (const entry of _discoverCommandsAt(projectPath, projectPath, opts, deadline, 'root', truncations)) {
     const key = `command:${entry.name}`;
     if (seenKey.has(key)) continue;
     seenKey.add(key);
@@ -348,7 +494,7 @@ function discoverProjectSkills(args) {
     for (const area of areas) {
       if (_now() > deadline) break;
       const areaBase = path.join(projectPath, area);
-      for (const entry of _discoverSkillsAt(areaBase, projectPath, opts, deadline, `area:${area}`)) {
+      for (const entry of _discoverSkillsAt(areaBase, projectPath, opts, deadline, `area:${area}`, truncations)) {
         const key = `skill:${entry.name}`;
         if (seenKey.has(key)) continue;
         seenKey.add(key);
@@ -360,7 +506,7 @@ function discoverProjectSkills(args) {
       // half-scanned area: doing so drops commands while keeping skills from
       // the same area, causing test/prod divergence under load (PR-82 blind spot
       // regression, CI failure yemi33#28135287117).
-      for (const entry of _discoverCommandsAt(areaBase, projectPath, opts, deadline, `area:${area}`)) {
+      for (const entry of _discoverCommandsAt(areaBase, projectPath, opts, deadline, `area:${area}`, truncations)) {
         const key = `command:${entry.name}`;
         if (seenKey.has(key)) continue;
         seenKey.add(key);
@@ -379,15 +525,39 @@ function discoverProjectSkills(args) {
     all.push(entry);
   }
 
-  // Deterministic ordering: alphabetical by name, then by path as tiebreaker
-  // so prompt rendering is stable across runs and OSes (readdir order varies).
+  // Deterministic ordering. When a scopeSubproject is set, entries under
+  // `<scopeSubproject>/` lead the list, then root-level, then other-sub-project entries;
+  // within each group the original name-then-path sort applies. When scopeSubproject
+  // is empty the group ranks are all equal so this reduces byte-for-byte to the
+  // historical global name-then-path sort (no regression for existing callers).
   all.sort((a, b) => {
+    if (scopeSubproject) {
+      const ga = _scopeGroup(a.path, scopeSubproject);
+      const gb = _scopeGroup(b.path, scopeSubproject);
+      if (ga !== gb) return ga - gb;
+    }
     if (a.name !== b.name) return a.name.localeCompare(b.name);
     return String(a.path || '').localeCompare(String(b.path || ''));
   });
 
   // Strip the internal _originLabel before returning (debugging-only).
-  return all.map(({ _originLabel, ...rest }) => rest); // eslint-disable-line no-unused-vars
+  const entries = all.map(({ _originLabel, ...rest }) => rest); // eslint-disable-line no-unused-vars
+  return { entries, truncations };
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.projectPath — absolute path to the project worktree / checkout
+ * @param {string} [args.scopeSubproject] — when set/non-empty, surface entries under
+ *   `<scopeSubproject>/` first, then root-level, then other-sub-project entries (see
+ *   discoverProjectSkillsWithDiagnostics). Unset/empty ⇒ global name-sort.
+ * @param {object} [args.opts] — override defaults (mostly for tests)
+ * @returns {Array<{kind:string,name:string,path:string,oneLineDescription:string,intents:string[]}>}
+ */
+function discoverProjectSkills(args) {
+  // Delegates to the diagnostics variant and returns only the entries array so
+  // existing array-returning callers keep working unchanged.
+  return discoverProjectSkillsWithDiagnostics(args).entries;
 }
 
 /**
@@ -478,6 +648,7 @@ function renderReviewSkillsBlock(entries) {
 
 module.exports = {
   discoverProjectSkills,
+  discoverProjectSkillsWithDiagnostics,
   filterByIntents,
   renderProjectSkillsBlock,
   classifyIntents,
@@ -494,5 +665,9 @@ module.exports = {
     _parseExplicitIntents,
     _extractSlashCommandsFromDoc,
     _listAreas,
+    detectDominantSubproject,
+    _normalizeScopeSubproject,
+    _entrySubproject,
+    _scopeGroup,
   },
 };

package/engine/live-checkout.js

@@ -362,6 +362,23 @@ async function prepareLiveCheckout(opts = {}) {
   // gitOpts.maxBuffer still wins (spread after the default).
   const baseOpts = { cwd: localPath, maxBuffer: LIVE_CHECKOUT_GIT_MAX_BUFFER, ...(gitOpts || {}) };
 
+  // ── Step 0 (W-mr3tayu4): clear a stale .git/index.lock BEFORE any preflight
+  //    git command runs. A leftover index.lock (from a crashed/killed git
+  //    process) makes every subsequent git invocation fail with "Unable to
+  //    create '<path>/.git/index.lock': File exists." In live-checkout mode the
+  //    engine never git-reset/cleans the operator tree, so nothing else clears
+  //    it — and the LIVE_CHECKOUT_FAILED classification is retryable, so every
+  //    automatic retry hit the SAME stale lock and failed identically forever
+  //    until an operator manually deleted it (observed incident: C:/office/src).
+  //    Mirror the worktree-mode self-heal (engine.js `git worktree add` retry
+  //    paths) by calling the SHARED age-gated (>300000ms) remover — see
+  //    engine.js#removeStaleIndexLock, which now also delegates here. Because
+  //    each retry re-enters spawnAgent → prepareLiveCheckout, running this at the
+  //    top also clears a lock that appears mid-retry, not just at first preflight.
+  //    The 5-min age gate is intentionally conservative so a lock held by a
+  //    currently-running git process is never removed out from under it.
+  shared.removeStaleIndexLock(localPath, { log: (level, msg) => logFn(msg, level) });
+
   // ── Step 1: git status --porcelain=v1 -b. Bail early on dirty tree. ─────
   // Skipped when `skipDirtyCheck:true` (issue #522): GVFS/VFS-for-Git repos
   // report all un-hydrated virtual files as modified — this is normal GVFS

package/engine/playbook.js

@@ -386,6 +386,15 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   // produce matches. Optional for the same reason as the review-only alias.
   'project_skills_block',
   'skip_project_skills',
+  // P-f52d81ba — monorepo-aware harness scoping. The engine derives a dominant
+  // sub-project for the dispatch (explicit meta.workdir first segment, or
+  // detectDominantSubproject over the current dispatch's changed paths) and threads
+  // it here so playbook.js can pass it as `scopeSubproject` into project-skill
+  // discovery. Optional with an empty-string default: single-root projects and
+  // mixed/root diffs legitimately resolve it to '' (flat discovery), and no
+  // playbook references {{dominant_subproject}} directly, so the unresolved-var check
+  // must stay quiet when it is unset.
+  'dominant_subproject',
   // M006 — typed handoff envelope fields. Set on a follow-up dispatch meta
   // when lifecycle.js queues the item after a completing agent so the
   // receiving agent has explicit context about who handed off and why.
@@ -401,6 +410,7 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   'prior_explore_context',
 ]);
 
+
 const PLAYBOOK_REQUIRED_VARS = {
   'implement':            ['item_id', 'item_name', 'branch_name', 'project_path'],
   'implement-shared':     ['item_id', 'item_name', 'branch_name', 'worktree_path'],
@@ -814,7 +824,27 @@ function renderPlaybook(type, vars) {
         const effectiveType = vars.parent_dispatch_type || type;
         const intents = intentsForPlaybook(effectiveType);
         if (intents.length > 0) {
-          const entries = discover.discoverProjectSkills({ projectPath });
+          // P-f52d81ba — monorepo-aware scoping. When the engine derived a
+          // dominant sub-project for this dispatch (git diff / PR files /
+          // references → detectDominantSubproject, threaded in via vars.dominant_subproject),
+          // surface that sub-project's skills FIRST. Empty/unset ⇒ today's flat
+          // global name-sort. Use the diagnostics variant so per-surface
+          // overflow (entries dropped past the maxFilesPerSurface cap) is
+          // observable instead of silent.
+          const scopeSubproject = typeof vars.dominant_subproject === 'string' ? vars.dominant_subproject : '';
+          const { entries, truncations } = discover.discoverProjectSkillsWithDiagnostics({
+            projectPath,
+            scopeSubproject,
+            opts: { maxFilesPerSurface: ENGINE_DEFAULTS.projectSkillMaxFilesPerSurface },
+          });
+          if (Array.isArray(truncations) && truncations.length > 0) {
+            log('warn', `discover-project-skills: ${truncations.length} surface(s) exceeded maxFilesPerSurface (entries dropped) for project ${matchedProject?.name || projectPath}${scopeSubproject ? ', subproject=' + scopeSubproject : ''}: ${truncations.map(t => `${t.dir} (${t.scanned}/${t.total})`).join('; ')}`);
+          }
+          // Stash discovery diagnostics on the vars object so the engine
+          // caller (spawnAgent) can record detected sub-project + truncations onto
+          // the dispatch record for later grounding/observability. Best-effort:
+          // callers that don't read it simply ignore the field.
+          vars._discoveryDiagnostics = { subproject: scopeSubproject, truncations: Array.isArray(truncations) ? truncations : [] };
           const filtered = discover.filterByIntents(entries, intents);
           // type === 'review' keeps PR-82 header copy + meta.review.* outcome
           // guidance; everything else uses the generic header that points at

package/engine/pr-action.js

@@ -154,14 +154,23 @@ const CREATE_PR_FOLLOWUP = Object.freeze({ kind: 'create-pr', label: 'Create PR'
  *                  changes through an isolated git worktree so nothing is ever
  *                  committed in the operator's live `main`. Defaults to `'live'`
  *                  for back-compat when a caller doesn't resolve it.
+ * `mainBranch`   — the project's resolved main/base branch
+ *                  (`shared.resolveMainBranch(project.localPath, project.mainBranch)`).
+ *                  In `'live'` mode the PR is ALWAYS built on a fresh branch off
+ *                  the up-to-date `origin/<mainBranch>` tip — never off whatever
+ *                  branch the live checkout happened to have checked out — so a
+ *                  stale/topic branch's unrelated commits can't leak into the new
+ *                  PR (W-mr3jbpru: "Create-PR reused stale topic branch as base").
+ *                  Falls back to `'main'` when a caller doesn't resolve it.
  *
  * Each chip: `{ kind:'create-pr', label, project, branch, message }` where
  * `message` is the Command Center turn the chip click should send.
  */
-function buildCreatePrFollowups({ project, branch, contextOnly = false, checkoutMode = 'live' } = {}) {
+function buildCreatePrFollowups({ project, branch, contextOnly = false, checkoutMode = 'live', mainBranch = '' } = {}) {
   const proj = (project && String(project).trim()) || '';
   if (!proj) return [];
   const br = branch && String(branch).trim() ? String(branch).trim() : '';
+  const mainRef = mainBranch && String(mainBranch).trim() ? String(mainBranch).trim() : 'main';
   const linkBody = contextOnly
     ? `{"url":"<new PR url>","project":"${proj}","contextOnly":true}`
     : `{"url":"<new PR url>","project":"${proj}","contextOnly":false}`;
@@ -185,21 +194,30 @@ function buildCreatePrFollowups({ project, branch, contextOnly = false, checkout
       `(6) finally call POST /api/pr-action/cleanup-create-pr-worktree with {"project":"${proj}","worktreePath":"<worktreePath>"} to remove the worktree. ` +
       `Never git-commit/-push in the live checkout. Then show me the PR URL.`;
   } else {
-    // Live-checkout projects: operate in place, but branch off main and restore
-    // the original branch so the PR branch is never left checked out.
-    const branchClause = br
-      ? `(the working tree is on branch ${br}; if ${br} is the project's default/main branch, create a new well-named branch off it and commit there rather than committing to ${br} directly)`
-      : 'on a new well-named branch off the project main branch';
+    // Live-checkout projects: operate in place, but ALWAYS build the PR on a
+    // fresh branch off the up-to-date origin/<mainBranch> tip — never off
+    // whatever branch the live checkout happened to have checked out. Trusting
+    // the current branch let a stale/topic branch's unrelated commits leak into
+    // the new PR (W-mr3jbpru). The stash → fetch → checkout -B → pop sequence
+    // captures the intended changes and re-applies them on a clean base; the
+    // original branch is restored at the end so the PR branch is never left
+    // checked out in the shared operator tree.
     const restoreClause = br
       ? `switch the working tree back to the ORIGINAL branch (${br})`
       : 'switch the working tree back to the original branch it started on';
     message =
       `Create a PR from the local changes you just made in the ${proj} project. ` +
       (br ? `Remember the working tree's current branch (${br}) as the ORIGINAL branch to return to when done. ` : '') +
-      `Steps: (1) in that project's working tree, stage and commit the modified files with a clear conventional-commit message ${branchClause}; ` +
-      `(2) push the branch; (3) open a PR against the project's main branch using the right CLI for the repo host (gh for GitHub, az repos for ADO); ` +
-      `(4) link it to the tracker by calling POST /api/pull-requests/link with ${linkBody} ${trackNote}; ` +
-      `(5) finally, ${restoreClause} — do not leave the new PR branch checked out. ` +
+      `IMPORTANT: do NOT commit onto whatever branch is currently checked out — it may carry unrelated commits. ` +
+      `ALWAYS build the PR on a fresh branch off the up-to-date ${mainRef} tip so no stale/topic branch commits leak into the new PR. ` +
+      `Steps: (1) stash your intended uncommitted changes with \`git stash push --include-untracked\`; ` +
+      `(2) fetch the latest base with \`git fetch origin ${mainRef}\`; ` +
+      `(3) create a fresh well-named branch off the remote main tip with \`git checkout -B <new-well-named-branch> origin/${mainRef}\` (never branch off whatever was previously checked out); ` +
+      `(4) re-apply your changes with \`git stash pop\` — if this reports a merge conflict, STOP and surface the conflict to me rather than force-resolving it silently; ` +
+      `(5) stage and commit the changes with a clear conventional-commit message; ` +
+      `(6) push the new branch; (7) open a PR against ${mainRef} using the right CLI for the repo host (gh for GitHub, az repos for ADO); ` +
+      `(8) link it to the tracker by calling POST /api/pull-requests/link with ${linkBody} ${trackNote}; ` +
+      `(9) finally, ${restoreClause} — do not leave the new PR branch checked out. ` +
       `Then show me the PR URL.`;
   }
   return [{ kind: CREATE_PR_FOLLOWUP.kind, label: CREATE_PR_FOLLOWUP.label, project: proj, branch: br || null, message }];

package/engine/queries.js

@@ -949,6 +949,15 @@ function _pickPrDedupeWinner(group, projects) {
   return { winner, dropped };
 }
 
+// W-mr3mvgfe — terminal PR statuses (done being polled/reviewed) get pushed
+// to the bottom of the PR tab's default sort. Includes `CLOSED` (a PR closed
+// without merging, distinct from `ABANDONED` but equally inactive — see
+// engine/github.js `newStatus = PR_STATUS.CLOSED` on `prData.state === 'closed'`
+// without `merged`) alongside `MERGED`/`ABANDONED`.
+function _isTerminalPrStatus(status) {
+  return status === PR_STATUS.MERGED || status === PR_STATUS.ABANDONED || status === PR_STATUS.CLOSED;
+}
+
 function getPullRequests(config) {
   const now = Date.now();
   if (_prsCache && (now - _prsCacheAt) < 1000) return _prsCache;
@@ -1018,6 +1027,12 @@ function getPullRequests(config) {
     allPrs.push(pr);
   }
   allPrs.sort((a, b) => {
+    // W-mr3mvgfe: group terminal PRs (merged/abandoned/closed) after active
+    // ones so a stale, already-resolved PR doesn't crowd out active work at
+    // the top of the list regardless of its `created` timestamp.
+    const aTerminal = _isTerminalPrStatus(a.status) ? 1 : 0;
+    const bTerminal = _isTerminalPrStatus(b.status) ? 1 : 0;
+    if (aTerminal !== bTerminal) return aTerminal - bTerminal;
     // W-mpej044m00076d63: sort by the full ISO `created` timestamp DESC so
     // same-day PRs preserve creation order (previously the slice-to-date
     // collapsed every PR opened on the same day into one bucket, then tied

package/engine/shared.js

@@ -2583,6 +2583,37 @@ function shellSafeGh(args, opts = {}) {
   }).then(({ stdout }) => stdout);
 }
 
+// W-mr3tayu4 — shared, age-gated stale `.git/index.lock` remover. Previously
+// lived only in engine.js and was called from the worktree-mode `git worktree
+// add` retry paths; it is now shared so engine/live-checkout.js#prepareLiveCheckout
+// (checkoutMode:'live' projects) can self-heal the same failure without a
+// circular import. Removes `<rootDir>/.git/index.lock` ONLY when it is older
+// than STALE_INDEX_LOCK_MAX_AGE_MS (5 min) — deliberately conservative so a lock
+// held by a currently-running git process is never deleted out from under it.
+// All fs/log seams are injectable for unit tests; production callers pass none.
+const STALE_INDEX_LOCK_MAX_AGE_MS = 300000;
+
+function removeStaleIndexLock(rootDir, opts = {}) {
+  const {
+    log: logOverride, // (level, msg) => void — defaults to the shared `log`
+    _exists = fs.existsSync,
+    _stat = fs.statSync,
+    _unlink = fs.unlinkSync,
+    _now = Date.now,
+  } = opts;
+  const emit = typeof logOverride === 'function' ? logOverride : (level, msg) => log(level, msg);
+  const lockFile = path.join(rootDir, '.git', 'index.lock');
+  try {
+    if (_exists(lockFile)) {
+      const age = _now() - _stat(lockFile).mtimeMs;
+      if (age > STALE_INDEX_LOCK_MAX_AGE_MS) {
+        _unlink(lockFile);
+        emit('warn', `Removed stale index.lock (${Math.round(age / 1000)}s old) in ${rootDir}`);
+      }
+    }
+  } catch (e) { emit('warn', 'git: ' + e.message); }
+}
+
 function shellSafeGit(args, opts = {}) {
   if (!Array.isArray(args)) {
     return Promise.reject(new TypeError('shellSafeGit: args must be an array'));
@@ -3372,6 +3403,15 @@ const ENGINE_DEFAULTS = {
   // closed by default. Set to false to fall back to the legacy
   // "only committed assets are visible" behavior.
   harnessPropagateProjectLocal: true,
+  // P-7c1a9e42 — cap on how many skill packs / command files
+  // engine/discover-project-skills.js reads per surface (root `.claude/skills`,
+  // each `<area>/.claude/skills`, etc.). Raised well above the module-level
+  // DEFAULTS.maxFilesPerSurface fallback (50) so large monorepo sub-projects (e.g.
+  // office/src/ocm/.claude/skills with ~80 packages) don't silently drop the
+  // most-relevant skills past the cap. engine/playbook.js threads this into the
+  // discovery `opts`; when no override is supplied the module falls back to its
+  // own DEFAULTS.maxFilesPerSurface. See docs/project-skills.md.
+  projectSkillMaxFilesPerSurface: 200,
   // P-49e1c8b7 — hermetic harness opt-out. When TRUE the spawned agent runs
   // with a known-empty harness surface around the worktree:
   //   - `--add-dir` is exactly `[minionsDir]` (user-scope skill/command/MCP
@@ -9374,6 +9414,8 @@ module.exports = {
   execSilent,
   shellSafeGh,
   shellSafeGit,
+  removeStaleIndexLock,
+  STALE_INDEX_LOCK_MAX_AGE_MS,
   shellSafeGitSync,
   validateGitRef,
   validateGhSlug,

package/engine.js

@@ -933,17 +933,13 @@ async function _fetchWithTransientRetry(args, opts, label) {
   }
 }
 
+// W-mr3tayu4 — thin wrapper around shared.removeStaleIndexLock. The age-gated
+// (>300000ms) stale-lock removal now lives in engine/shared.js so both the
+// worktree-add retry paths here and engine/live-checkout.js#prepareLiveCheckout
+// share one implementation (no circular import). Kept as a named local because
+// three internal call sites and the test harness reference `removeStaleIndexLock`.
 function removeStaleIndexLock(rootDir) {
-  const lockFile = path.join(rootDir, '.git', 'index.lock');
-  try {
-    if (fs.existsSync(lockFile)) {
-      const age = Date.now() - fs.statSync(lockFile).mtimeMs;
-      if (age > 300000) {
-        fs.unlinkSync(lockFile);
-        log('warn', `Removed stale index.lock (${Math.round(age / 1000)}s old) in ${rootDir}`);
-      }
-    }
-  } catch (e) { log('warn', 'git: ' + e.message); }
+  return shared.removeStaleIndexLock(rootDir);
 }
 
 async function runWorktreeAdd(rootDir, worktreePath, addArgs, gitOpts, worktreeCreateRetries) {
@@ -1927,6 +1923,38 @@ async function recoverPartialWorktree(rootDir, worktreePath, branchName, gitOpts
   }
 }
 
+// P-f52d81ba — persist the dispatch's detected monorepo sub-project (+ any per-surface
+// skill-discovery truncations the render surfaced) onto the dispatch record so
+// later grounding/observability can see which sub-project scoped discovery + harness
+// propagation. Best-effort: mutation failures must never block the spawn. Only
+// writes fields that carry a value so unset sub-projects leave the record untouched.
+function _recordDispatchDiscoveryDiagnostics(id, dispatchItem, subproject, diagnostics) {
+  try {
+    const dominantSubproject = (typeof subproject === 'string' && subproject) ? subproject : undefined;
+    const truncations = diagnostics && Array.isArray(diagnostics.truncations) && diagnostics.truncations.length
+      ? diagnostics.truncations
+      : undefined;
+    if (dominantSubproject === undefined && truncations === undefined) return;
+    mutateDispatch((dispatch) => {
+      for (const queue of ['pending', 'active', 'completed']) {
+        const arr = Array.isArray(dispatch?.[queue]) ? dispatch[queue] : null;
+        if (!arr) continue;
+        const found = arr.find(d => d && d.id === id);
+        if (!found) continue;
+        if (dominantSubproject !== undefined) found._dominantSubproject = dominantSubproject;
+        if (truncations !== undefined) found._skillDiscoveryTruncations = truncations;
+      }
+      return dispatch;
+    });
+    if (dispatchItem) {
+      if (dominantSubproject !== undefined) dispatchItem._dominantSubproject = dominantSubproject;
+      if (truncations !== undefined) dispatchItem._skillDiscoveryTruncations = truncations;
+    }
+  } catch (e) {
+    log('warn', `record discovery diagnostics failed for ${id} (non-fatal): ${e.message}`);
+  }
+}
+
 // Seed a spawned agent's COPILOT_HOME mcp-config as a copy of the operator's
 // `~/.copilot/mcp-config.json` MINUS the servers in
 // `engine.copilotAgentDisabledMcpServers`, then point COPILOT_HOME at it.
@@ -3894,6 +3922,45 @@ async function spawnAgent(dispatchItem, config) {
 
   updateAgentStatus(id, AGENT_STATUS.READY, 'Worktree ready, preparing to spawn process');
 
+  // ── P-f52d81ba — derive the effective monorepo sub-project for this dispatch ──────
+  // Feeds BOTH project-skill discovery (scopeSubproject → sub-project's skills lead the
+  // rendered project_skills_block) and project-local harness propagation
+  // (workdir clip → only the sub-project's --project-harness-dir roots are surfaced).
+  // Precedence:
+  //   1. Explicit meta.workdir wins — effective sub-project = its first segment. No
+  //      diff work (the operator already declared the target sub-package).
+  //   2. Else best-effort from the CURRENT dispatch's diff: `git diff
+  //      --name-only <main>...HEAD` in this worktree → detectDominantSubproject.
+  //   3. Else '' (flat discovery / unclipped harness — today's behavior).
+  // Contract: never blocks dispatch, never changes agent cwd (only an explicit
+  // meta.workdir moves cwd, applied separately below), and degrades to '' on
+  // any failure. Derived from THIS worktree's HEAD so a follow-up/parent's
+  // stale diff can't leak in (AC: current-dispatch diff only).
+  let _effectiveSubproject = '';
+  try {
+    if (validatedWorkdir) {
+      _effectiveSubproject = String(validatedWorkdir).replace(/\\/g, '/').replace(/^\/+/, '').split('/')[0] || '';
+    } else if (worktreePath && fs.existsSync(worktreePath) && project?.localPath) {
+      let _subprojectChangedPaths = [];
+      try {
+        const _subprojectBase = sanitizeBranch(shared.resolveMainBranch(rootDir, project.mainBranch));
+        const _subprojectDiff = await execAsync(`git diff --name-only ${_subprojectBase}...HEAD`, { ..._gitOpts, cwd: worktreePath, timeout: 10000 });
+        _subprojectChangedPaths = (_subprojectDiff.stdout || '').split('\n').map(s => s.trim()).filter(Boolean);
+      } catch (e) {
+        log('debug', `subproject-detect: git diff failed for ${id} (flat discovery): ${e.message}`);
+      }
+      if (_subprojectChangedPaths.length) {
+        const { detectDominantSubproject } = require('./engine/discover-project-skills')._internal;
+        const _det = detectDominantSubproject({ projectPath: project.localPath, changedPaths: _subprojectChangedPaths });
+        if (_det && _det.confident && _det.subproject) _effectiveSubproject = _det.subproject;
+      }
+    }
+  } catch (e) {
+    log('warn', `subproject-detect failed for ${id} (non-fatal, flat discovery): ${e.message}`);
+    _effectiveSubproject = '';
+  }
+
+  let _refreshedDiscoveryDiagnostics = null;
   if (worktreePath && meta?.source === 'work-item' && meta?.item?.branchStrategy === 'shared-branch') {
     const refreshed = renderProjectWorkItemPromptForAgent(
       meta.item,
@@ -3903,15 +3970,21 @@ async function spawnAgent(dispatchItem, config) {
       project,
       rootDir,
       branchName,
-      { worktreePath }
+      { worktreePath, dominantSubproject: _effectiveSubproject }
     );
     if (refreshed.prompt) {
       taskPrompt = refreshed.prompt;
       fullTaskPrompt = buildFullTaskPrompt(taskPrompt);
       safeWrite(promptPath, fullTaskPrompt);
-      log('info', `Refreshed shared-branch prompt for ${id} with worktree ${worktreePath}`);
+      log('info', `Refreshed shared-branch prompt for ${id} with worktree ${worktreePath}${_effectiveSubproject ? ` (subproject=${_effectiveSubproject})` : ''}`);
     }
+    _refreshedDiscoveryDiagnostics = refreshed.discoveryDiagnostics || null;
   }
+  // Record the detected sub-project (+ any per-surface skill-discovery truncations the
+  // shared-branch re-render surfaced) onto the dispatch record for later
+  // grounding/observability. Sub-project-only for non-re-render dispatches (their
+  // prompt was rendered at dispatch-build time; truncations are logged there).
+  _recordDispatchDiscoveryDiagnostics(id, dispatchItem, _effectiveSubproject, _refreshedDiscoveryDiagnostics);
 
   // Inject dirty file list when worktree has uncommitted changes (e.g., max_turns retry)
   // This signals to the respawned agent that prior work exists in the worktree (#960)
@@ -4223,7 +4296,12 @@ async function spawnAgent(dispatchItem, config) {
       const filteredDirs = shared.filterProjectHarnessDirsForWorkdir(candidateDirs, {
         projectLocalPath: project.localPath,
         worktreePath,
-        workdir: validatedWorkdir,
+        // P-f52d81ba — clip to the effective sub-project. Explicit meta.workdir wins
+        // (validatedWorkdir, possibly multi-segment); otherwise use the
+        // auto-derived dominant sub-project (single first-level segment) so an
+        // ocm/-dominant diff surfaces only ocm/'s --project-harness-dir roots.
+        // Empty ⇒ no clip (today's whole-project harness surface).
+        workdir: validatedWorkdir || _effectiveSubproject || null,
       });
       for (const abs of filteredDirs) {
         if (!fs.existsSync(abs)) continue;
@@ -4231,7 +4309,7 @@ async function spawnAgent(dispatchItem, config) {
         propagatedProjectHarnessDirs.push(abs);
       }
       if (projectHarnessArgs.length) {
-        log('debug', `Project-local harness propagation: ${projectHarnessArgs.length / 2} dir(s) for ${id} (${worktreePath}${validatedWorkdir ? ', workdir=' + validatedWorkdir : ''})`);
+        log('debug', `Project-local harness propagation: ${projectHarnessArgs.length / 2} dir(s) for ${id} (${worktreePath}${validatedWorkdir ? ', workdir=' + validatedWorkdir : (_effectiveSubproject ? ', subproject=' + _effectiveSubproject : '')})`);
       }
     } catch (err) {
       log('warn', `Project-local harness propagation failed for ${id} (non-fatal): ${err.message}`);
@@ -7699,6 +7777,30 @@ function _buildRunnerBriefVars(item, project) {
   }
 }
 
+// P-f52d81ba — sync effective-sub-project derivation for the build-time prompt render
+// (renderProjectWorkItemPromptForAgent runs synchronously, so no git diff).
+// Explicit meta.workdir wins (first segment). Otherwise best-effort from the
+// work item's references[*].path via detectDominantSubproject. Returns '' (flat
+// discovery) on anything unresolved. spawnAgent's async re-render overrides
+// this with a git-diff-derived sub-project via options.dominantSubproject.
+function _deriveDominantSubprojectSync(item, project) {
+  try {
+    const wd = item && item.meta && item.meta.workdir;
+    if (typeof wd === 'string' && wd.trim()) {
+      return wd.replace(/\\/g, '/').replace(/^\/+/, '').split('/')[0] || '';
+    }
+    const projectPath = project && project.localPath;
+    if (!projectPath) return '';
+    const paths = (item && Array.isArray(item.references))
+      ? item.references.map(r => (r && typeof r.path === 'string') ? r.path : '').filter(Boolean)
+      : [];
+    if (paths.length === 0) return '';
+    const { detectDominantSubproject } = require('./engine/discover-project-skills')._internal;
+    const det = detectDominantSubproject({ projectPath, changedPaths: paths });
+    return (det && det.confident && det.subproject) ? det.subproject : '';
+  } catch { return ''; }
+}
+
 /**
  * Scan work-items.json for manually queued tasks
  */
@@ -7873,6 +7975,14 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     // Either flag suppresses both blocks on the dispatch.
     skip_project_review_skills: !!(item.meta && item.meta.skipProjectReviewSkills),
     skip_project_skills: !!(item.meta && (item.meta.skipProjectSkills || item.meta.skipProjectReviewSkills)),
+    // P-f52d81ba — effective monorepo sub-project for scoped skill discovery. When the
+    // async caller (spawnAgent) supplies a git-diff-derived sub-project it wins (even
+    // ''); otherwise derive best-effort from explicit meta.workdir /
+    // references[*].path. Empty ⇒ flat discovery. playbook.js reads this as the
+    // discovery scopeSubproject.
+    dominant_subproject: (typeof options.dominantSubproject === 'string')
+      ? options.dominantSubproject
+      : _deriveDominantSubprojectSync(item, project),
     // M006 — typed handoff envelope. Set on follow-up dispatch metas by
     // lifecycle.js when queuing an item after a completing agent. The
     // renderPlaybook path injects a "Handoff Context" section when truthy
@@ -7892,10 +8002,16 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
   if (playbookName === 'work-item' && workType === WORK_TYPE.REVIEW) {
     log('info', `Work item ${item.id} is type "review" but has no PR — using work-item playbook`);
   }
+  const prompt = item.prompt || renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars) || item.description;
   return {
     needsReview: false,
     checkpointCount: cpResult.checkpointCount,
-    prompt: item.prompt || renderPlaybook(playbookName, vars) || renderPlaybook('work-item', vars) || item.description,
+    prompt,
+    // P-f52d81ba — surface the discovery diagnostics renderPlaybook stashed on
+    // the vars object (detected sub-project + per-surface truncations) so spawnAgent
+    // can record them onto the dispatch record. null when no playbook render
+    // ran (item.prompt short-circuit) or discovery was skipped.
+    discoveryDiagnostics: vars._discoveryDiagnostics || null,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2320",
+  "version": "0.1.2322",
   "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/prompts/cc-system.md

@@ -89,16 +89,25 @@ If you start a small task and discover it's actually Medium (3+ files, more tool
 
 When genuinely in doubt about the size, delegate — agents have isolated worktrees, full tool access, durable work-item tracking, and no turn limits.
 
+### HARD STOP — never edit files yourself in a live/hybrid project
+This overrides everything above, **including the direct-handling override**. For any project whose effective checkout mode is `live` (or `hybrid` for a code-authoring work-item type — `implement`/`fix`/`docs`/`decompose`), you MUST NOT use `Edit`/`Write`/`Bash` (or any tool) to mutate files inside that project's `localPath`, **regardless of task size** — not even a Small 1-line change, and not even when the human explicitly says to do it yourself. The Step-3 "do it yourself" allowance and the Step-1 direct-handling override do **not** apply to writes inside a live/hybrid checkout.
+
+Why: live-mode projects have no worktree isolation — the engine runs agents in-place inside `localPath`, caps dispatch to one mutating operation at a time, and refuses to dispatch on a dirty tree (`live-checkout-dirty`, non-retryable). A stray CC edit leaves the checkout dirty in a way the dispatch bookkeeping does not track, and that dirty state then **blocks every subsequent live-mode dispatch** on the project until a human manually cleans it up. It is NOT covered by the engine's dispatch-time auto-stash/auto-reset recovery — those only run as part of an actual dispatch preflight, never for stray CC edits.
+
+Instead, when a change is needed in a live/hybrid project, **dispatch a normal work item** (`POST /api/work-items`, `type: "implement"` or `"fix"` as usual) and let the engine own the live-checkout dispatch path (dirty-tree refusal, single-mutating-dispatch cap, auto-stash/auto-reset). Do not try to shortcut it with your own edit.
+
+Read-only inspection is still fine to do yourself in a live/hybrid checkout: viewing files, `git status`/`git log`/`git diff`, and non-mutating build/test commands are all fair game. The restriction is specifically about **writes**. See "Project checkout modes (worktree / live / hybrid)" below for the mode contract this rule protects.
+
 ### After you make a local code edit yourself — offer to open a PR
-When you edit files **yourself** in a configured project's working tree (the Step-3 "do it yourself" path — NOT a change a dispatched agent made in its own worktree), don't leave the diff sitting uncommitted. After you finish editing, call:
+This flow is **worktree-mode only** — it applies solely to projects whose effective checkout mode is `worktree`. For `live`/`hybrid` projects you never edit files yourself (see the HARD STOP above), so there is nothing to PR from a CC edit. If you ever find uncommitted changes sitting in a live-mode project's checkout anyway, do **not** commit or push them yourself — just report the dirty state to the user and let them decide how to clean it up.
+
+When you edit files **yourself** in a configured worktree-mode project's working tree (the Step-3 "do it yourself" path — NOT a change a dispatched agent made in its own worktree), don't leave the diff sitting uncommitted. After you finish editing, call:
 ```
 curl -s -X POST http://localhost:{{dashboard_port}}/api/pr-action/offer-create-pr \
   -H 'Content-Type: application/json' -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
   -d '{"project":"<project name>"}'
 ```
-This checks the project's working tree (`git status --porcelain`) and, when there are uncommitted changes, returns a **`[Create PR]`** follow-up chip to the user (same chip mechanism as the `pr-action` `[Comment]`/`[Fix once]`/`[Track for auto-fix]` chips). When the user clicks it, you'll receive a turn with **explicit step-by-step instructions — follow them exactly**. The instructions adapt to the project's checkout pattern, so just do what the turn says:
-- **Worktree-mode projects** (the default): the turn tells you to first `POST /api/pr-action/prepare-create-pr-worktree {"project":"…"}`. The server moves your uncommitted changes into an **isolated worktree** and restores the live checkout clean, returning `{worktreePath, branch, baseBranch}`. You then run **all git from inside `worktreePath`** (`git -C <worktreePath> …`) to commit/push/open the PR, then `POST /api/pr-action/cleanup-create-pr-worktree` to remove it. **Never commit, branch, or push in the live checkout** — that leaks commits onto the operator's `main`.
-- **Live-mode projects**: the turn tells you to commit on a new branch off main in the live checkout and switch back to the original branch when done.
+This checks the project's working tree (`git status --porcelain`) and, when there are uncommitted changes, returns a **`[Create PR]`** follow-up chip to the user (same chip mechanism as the `pr-action` `[Comment]`/`[Fix once]`/`[Track for auto-fix]` chips). When the user clicks it, you'll receive a turn with **explicit step-by-step instructions — follow them exactly**. Because you only ever edit files yourself in worktree-mode projects (see the HARD STOP above), this is always the worktree-mode flow: the turn tells you to first `POST /api/pr-action/prepare-create-pr-worktree {"project":"…"}`. The server moves your uncommitted changes into an **isolated worktree** and restores the live checkout clean, returning `{worktreePath, branch, baseBranch}`. You then run **all git from inside `worktreePath`** (`git -C <worktreePath> …`) to commit/push/open the PR, then `POST /api/pr-action/cleanup-create-pr-worktree` to remove it. **Never commit, branch, or push in the live checkout** — that leaks commits onto the operator's `main`.
 
 Pass `"contextOnly":true` if the PR should be tracked-but-not-auto-reviewed; omit it to have the engine auto-manage the PR (review → fix → re-review → auto-merge). If `hasChanges` is `false`, there's nothing to PR — skip the offer. Don't commit/push on your own initiative; surface the chip and let the user decide.
 
@@ -327,6 +336,8 @@ Every configured project has an effective **checkout mode** — surfaced in your
 - **`live`** — agents run **in-place** inside the project's `localPath` (no worktree). The engine caps this to **one mutating dispatch at a time** per project and **refuses on a dirty tree**. Use only when worktrees are unworkable (e.g. Android `repo`, submodules, deep Windows paths, emulators that bind the real checkout).
 - **`hybrid`** — `live` **plus** a `liveValidation: { type, autoDispatch }` block. Coding work items (`implement`/`fix`/`docs`/`decompose`) author in **isolated worktrees** (full parallelism), while **only** work items whose type matches `liveValidation.type` (e.g. `build-and-test`) run **in-place on the live checkout**. This is the best of both: parallel code authoring + a real on-disk build/validation that can't run in a worktree. `type` accepts a single string (e.g. `"build-and-test"`) or an array of strings (e.g. `["implement","fix"]`) to route multiple work-item types to the live checkout at once.
 
+**CC never writes into a live/hybrid checkout itself.** Because `live` (and the code-authoring surface of `hybrid`) runs in-place with no worktree isolation, a one-off CC edit inside such a project's `localPath` leaves the tree dirty and blocks every future live-mode dispatch (the engine refuses on a dirty tree, `live-checkout-dirty`, non-retryable — and it does not track or auto-recover stray CC edits). So for any needed change in a `live`/`hybrid` project you **dispatch a work item** and let the engine own the live-checkout path; you never `Edit`/`Write`/`Bash`-mutate files there yourself, regardless of task size or a direct-handling override. Read-only inspection remains fine. This is the same rule stated up top under "HARD STOP — never edit files yourself in a live/hybrid project"; the two sections agree by design.
+
 **When to recommend hybrid:** the project's build/test/validation genuinely cannot run in an isolated worktree (it needs the real checkout — submodules, a `repo`-managed tree, an emulator/dev-server bound to `localPath`, deep-path tooling), **but** you still want coding agents to work in parallel rather than serialize through the single live checkout. If the *whole* workflow must run on the real tree, use plain `live`. If nothing needs the real tree, stay on `worktree`.
 
 **Configuring it** (via the projects array on `POST /api/settings` — never hand-edit `config.json`):