@yemi33/minions 0.1.2321 → 0.1.2323

package/engine/live-checkout.js

@@ -220,6 +220,25 @@ function _collectAutoCleanablePaths(dirtyFiles) {
   return cleanable.length > 0 ? cleanable : null;
 }
 
+// W-mr3lokxs — Cap a porcelain dirty-file list before it is embedded verbatim
+// into a live-checkout-dirty inbox alert body. On GVFS/virtual repos (see the
+// "~120k virtual dirty files" note in prepareLiveCheckout below) a single
+// refusal can report tens of thousands of "modified" paths; embedding the full
+// list produced multi-MB / tens-of-MB alert bodies that then bloated the
+// knowledge base (240 dirty-worktree dumps ≈ 113 MB). Keep the first `maxLines`
+// entries and replace the remainder with a single truncation-notice line so the
+// alert stays human-scannable and bounded. Pure/deterministic — exported for
+// unit testing.
+const DIRTY_ALERT_MAX_LINES = 200;
+function capDirtyFileLines(dirtyFiles, maxLines = DIRTY_ALERT_MAX_LINES) {
+  const lines = Array.isArray(dirtyFiles) ? dirtyFiles : [];
+  const cap = Number.isInteger(maxLines) && maxLines > 0 ? maxLines : DIRTY_ALERT_MAX_LINES;
+  if (lines.length <= cap) return lines.slice();
+  const kept = lines.slice(0, cap);
+  kept.push(`... and ${lines.length - cap} more (run \`git status --porcelain=v1 -b\` locally for the full list)`);
+  return kept;
+}
+
 // issue #608 — detects a branch name that the ENGINE created for a live-mode
 // dispatch (never the operator's own branch). Matches ONLY the literal
 // `work/<wi-id>` convention produced by `shared.deriveWorkItemBranchName` —
@@ -362,6 +381,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
@@ -1234,5 +1270,7 @@ module.exports = {
   _looksLikeAgentBranch,
   _extractBranchFromPorcelainHeader,
   _commitAgentWipWithRetry,
+  capDirtyFileLines,
+  DIRTY_ALERT_MAX_LINES,
   LIVE_CHECKOUT_AUTO_CLEAN_PATTERNS,
 };

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/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'));
@@ -2796,11 +2827,44 @@ const KB_READABLE_CATEGORIES = Object.freeze([
   'consolidated', 'consolidation', 'consolidations',
   'team-memory', 'general', 'patterns',
 ]);
+/**
+ * Detect engine-authored system alerts (dirty-tree refusals, worktree-skip-live
+ * guard notices, blocked/conflicted live-checkout dispatches, managed-spawn
+ * failures, ADO-auth alerts, …). These are operational noise, NOT durable
+ * reusable knowledge, and the same underlying incident recurs verbatim across
+ * many different inbox filenames (one per worktree/date), so consolidation
+ * must never copy their full body into knowledge/ as a distinct "new" entry
+ * per recurrence — see W-mr3pi9de (worktree-skip-live note titles were
+ * identical across every firing regardless of worktree, producing 30+
+ * duplicate-titled knowledge/project-notes/*.md entries on a single day) and
+ * the sibling W-mr3lokxs fix for live-checkout-dirty alerts.
+ *
+ * `engine/dispatch.js#writeInboxAlert` names every file `engine-alert-<slug>-
+ * <date>.md`, so the filename prefix is one signal. `shared.js#_writeWorktree
+ * SkipLiveInboxNote` (and any other engine-authored note) stamps frontmatter
+ * `agent: engine`, accepted as a second signal so alerts written under a
+ * different filename convention are still recognized.
+ */
+function isEngineSystemAlert(name, content) {
+  const nameLower = (name || '').toLowerCase();
+  if (nameLower.includes('engine-alert-') || nameLower.includes('engine-worktree-skip-live-')) return true;
+  const fmMatch = String(content || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (fmMatch && /^agent:\s*engine\s*$/im.test(fmMatch[1])) return true;
+  return false;
+}
+
 /**
  * Classify an inbox item into a knowledge base category.
  * Single source of truth — used by consolidation.js (both LLM and regex paths).
  */
 function classifyInboxItem(name, content) {
+  // W-mr3pi9de / W-mr3lokxs — engine-authored system alerts are operational
+  // noise. Route them to 'project-notes' BEFORE the content-substring
+  // heuristics below, so a note whose body incidentally contains substrings
+  // like 'lint', 'review', or 'pr-' can't be misclassified into
+  // build-reports/reviews. classifyToKnowledgeBase additionally forces these
+  // non-reusable and content-hash-dedups them regardless of category.
+  if (isEngineSystemAlert(name, content)) return 'project-notes';
   const nameLower = (name || '').toLowerCase();
   const contentLower = (content || '').toLowerCase();
   if (nameLower.includes('review') || nameLower.includes('pr-') || nameLower.includes('pr4') || nameLower.includes('feedback')) return 'reviews';
@@ -3372,6 +3436,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
@@ -8853,7 +8926,13 @@ function _writeWorktreeSkipLiveInboxNote(worktreePath, callerTag, blockingInfo)
       `date: ${date}`,
       '---',
       '',
-      `# Engine skipped worktree wipe — live dispatch guard fired (W-mq5rwwss000f30a7)`,
+      // W-mr3pi9de — embed the actual worktree basename, not a hardcoded
+      // literal. The previous fixed string made every note (and therefore
+      // every knowledge/project-notes/*.md entry consolidation wrote from
+      // it) share byte-identical titles regardless of which worktree fired
+      // the guard, defeating uniquePath's -2/-3/… suffixing and flooding the
+      // KB with near-duplicate-content entries under different numbers.
+      `# Engine skipped worktree wipe — live dispatch guard fired (${base})`,
       '',
       `- caller: ${callerTag || 'unknown'}`,
       `- worktree: ${worktreePath}`,
@@ -9374,6 +9453,8 @@ module.exports = {
   execSilent,
   shellSafeGh,
   shellSafeGit,
+  removeStaleIndexLock,
+  STALE_INDEX_LOCK_MAX_AGE_MS,
   shellSafeGitSync,
   validateGitRef,
   validateGhSlug,
@@ -9392,6 +9473,7 @@ module.exports = {
   KB_CATEGORIES,
   KB_READABLE_CATEGORIES,
   classifyInboxItem,
+  isEngineSystemAlert,
   ENGINE_DEFAULTS,
   resolvePollFlag, // P-c4d8e1a3 — granular per-poller flag resolution
   resolveAgentCli, resolveCcCli, resolveCcUseWorkerPool, resolveAgentModel, resolveCcModel,

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.
@@ -2555,7 +2583,7 @@ async function spawnAgent(dispatchItem, config) {
         '## Dirty files (`git status --porcelain=v1 -b`)',
         '',
         '```',
-        ...(_dirtyFiles.length > 0 ? _dirtyFiles : ['(none reported)']),
+        ...(_dirtyFiles.length > 0 ? _liveCheckout.capDirtyFileLines(_dirtyFiles) : ['(none reported)']),
         '```',
         '',
         _autoCleanupEnabled
@@ -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.2321",
+  "version": "0.1.2323",
   "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`):