@yemi33/minions 0.1.2228 → 0.1.2229

package/bin/minions.js

@@ -1168,6 +1168,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     minions cleanup                  Clean temp files, worktrees, zombies
     minions pr comment <repo> <n>    Post a marker-prepended PR comment via gh
                                        --agent <id> --kind <k> [--wi <id>] (--body-file <f> | --body <text>)
+                                       [--harness-file <f> | --harness-json <j>] folds in a "Harnesses used" section
     minions nuke --confirm           Factory reset (delete state, reset config to defaults)
     minions uninstall --confirm      Remove everything + uninstall npm package
 

package/docs/harness-transparency.md

@@ -110,11 +110,15 @@ evaluation pass) can see what tooling drove a dispatch:
    and ⚠️-marked), and returns `''` for an empty/absent record. The GitHub
    comment path folds it in via `engine/gh-comment.js#buildMinionsCommentBody`
    (optional `harnessUsed` arg, threaded through `postPrComment` /
-   `postPrReviewComment` / `postPrReview`); the Azure DevOps path has no
-   engine-side comment poster (agents post via `az repos pr comment` / REST),
-   so review/fix agents append the **byte-identical** section themselves per
-   `playbooks/shared-rules.md` → "Harness transparency / self-report". Both
-   surfaces consume the one renderer, so there is no second formatter to drift.
+   `postPrReviewComment` / `postPrReview`); the Azure DevOps path mirrors it via
+   `engine/ado-comment.js#postAdoPrComment` (same builder, same `harnessUsed`
+   arg). Both posters are reached from the `minions pr comment` CLI, which turns
+   `--harness-file` / `--harness-json` into the grounded record and folds the
+   **byte-identical** section in for the agent. Only the raw `gh pr comment` /
+   `az repos pr comment` / REST fallbacks bypass that chokepoint, so on those
+   paths review/fix agents append the section themselves per
+   `playbooks/shared-rules.md` → "Harness transparency / self-report". Every
+   surface consumes the one renderer, so there is no second formatter to drift.
 2. **notes/inbox digest** — harness usage is summarized into the learnings /
    inbox stream that feeds consolidation, so cross-task patterns ("everyone
    reaches for skill X on Android fixes") become visible to the team-memory

package/engine/cli.js

@@ -250,7 +250,7 @@ const CLI_COMMAND_DOCS = Object.freeze({
   'mcp-sync': { args: '',                      summary: 'Print harness propagation diagnostic (same source as `minions doctor --harness`; read-only, no writes)' },
   doctor:     { args: '[--harness]',           summary: 'Check prerequisites and runtime health (--harness: print harness propagation diagnostic)' },
   config:     { args: 'set-cli <R> [--model M]', summary: 'Persist defaultCli/defaultModel without starting' },
-  pr:         { args: 'comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] [--body-file <f>|--body <text>]', summary: 'Post a marker-prepended PR comment via gh' },
+  pr:         { args: 'comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] [--harness-file <f>|--harness-json <j>] [--body-file <f>|--body <text>]', summary: 'Post a marker-prepended PR comment via gh' },
   bridge:     { args: 'status|health|enable|disable',         summary: 'Constellation bridge: toggle and inspect the read-only cross-repo feed' },
 });
 
@@ -413,6 +413,68 @@ function _applyRuntimeFlags({ cli, model, modelExplicit }) {
   return { warnings, applied: true };
 }
 
+// resolveHarnessUsedForComment(flags) — P-7a3c9e21. Turn the `minions pr comment`
+// harness flags into a grounded `harnessUsed` record suitable for the posters'
+// `harnessUsed` param (engine/gh-comment.js / engine/ado-comment.js), which fold
+// it via buildMinionsCommentBody -> buildHarnessUsedSection.
+//
+// Source precedence: `--harness-file <path>` (JSON on disk) wins over the inline
+// `--harness-json <json>` convenience; neither supplied -> returns undefined so
+// the comment body is byte-identical to today (no section). Read/parse failures
+// are HARD errors (process.exit(2) with the offending message) — never a silent
+// drop. Grounding uses the spawn-time `_harnessPropagated` manifest located by
+// dispatch id (explicit `--dispatch-id` -> else basename(MINIONS_COMPLETION_REPORT,
+// '.json')); an unresolvable manifest passes null, marking every entry
+// grounded:false — the honest "no record" state, not a fatal condition.
+function resolveHarnessUsedForComment(flags) {
+  const fileArg = flags['harness-file'];
+  const jsonArg = flags['harness-json'];
+
+  let raw;
+  if (fileArg !== undefined) {
+    try {
+      raw = fs.readFileSync(fileArg, 'utf8');
+    } catch (e) {
+      console.error(`error: could not read --harness-file ${fileArg}: ${e.message}`);
+      process.exit(2);
+    }
+  } else if (jsonArg !== undefined) {
+    raw = String(jsonArg);
+  } else {
+    return undefined;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    const src = fileArg !== undefined ? `--harness-file ${fileArg}` : '--harness-json';
+    console.error(`error: invalid JSON in ${src}: ${e.message}`);
+    process.exit(2);
+  }
+
+  // Resolve the grounding manifest best-effort: explicit id -> completion-report
+  // basename. A missing/unresolvable manifest is non-fatal (groundHarnessUsed
+  // with null propagated marks everything grounded:false).
+  const dispatchId = flags['dispatch-id']
+    || path.basename(process.env.MINIONS_COMPLETION_REPORT || '', '.json')
+    || undefined;
+  let propagated = null;
+  if (dispatchId) {
+    try {
+      const dispatch = getDispatch();
+      for (const queue of ['active', 'completed', 'pending']) {
+        const list = Array.isArray(dispatch?.[queue]) ? dispatch[queue] : null;
+        if (!list) continue;
+        const found = list.find(d => d && d.id === dispatchId);
+        if (found && found._harnessPropagated) { propagated = found._harnessPropagated; break; }
+      }
+    } catch { propagated = null; }
+  }
+
+  return shared.groundHarnessUsed(parsed, propagated);
+}
+
 const commands = {
   start(...startArgs) {
     // Apply --cli / --model fleet flags before any engine wiring touches
@@ -1982,6 +2044,11 @@ const commands = {
       console.log('  GitHub: minions pr comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] (--body-file <path> | --body <text>)');
       console.log('  ADO:    minions pr comment <prNumber> --host ado --ado-org <org> --ado-project <proj> --repo-id <id> --agent <id> --kind <k> [--wi <id>] (--body-file <path> | --body <text>)');
       console.log('');
+      console.log('Optional harness self-report (folded into the collapsible "Harnesses used" section):');
+      console.log('  --harness-file <path>   JSON file with the { skills, mcpServers, commands, docs } record (wins over --harness-json)');
+      console.log('  --harness-json <json>   same record inline as a JSON string');
+      console.log('  --dispatch-id <id>      grounding manifest override (else basename of $MINIONS_COMPLETION_REPORT)');
+      console.log('');
       console.log('Posts a PR comment with the hidden minions marker, the collapsible');
       console.log('"Harnesses used" section, and the brand link folded in by the shared');
       console.log('builder — so engine classifiers identify agent-authored comments by');
@@ -2040,6 +2107,12 @@ const commands = {
       process.exit(2);
     }
 
+    // P-7a3c9e21 — thread the consulted-sources footprint into both posters so
+    // the auto-folded "Harnesses used" <details> section the help already
+    // promises is actually rendered. Resolved once (host-neutral); absent flags
+    // -> undefined -> body byte-identical to today.
+    const harnessUsed = resolveHarnessUsedForComment(flags);
+
     // ── Azure DevOps: <prNumber> --host ado --ado-org --ado-project --repo-id ──
     if (isAdo) {
       const [prNumberRaw] = positional;
@@ -2059,7 +2132,7 @@ const commands = {
       const orgBase = flags['org-base'] || `https://dev.azure.com/${adoOrg}`;
       const adoComment = require('./ado-comment');
       adoComment.postAdoPrComment({
-        orgBase, project, repositoryId, prNumber, body, agentId, kind, workItemId,
+        orgBase, project, repositoryId, prNumber, body, agentId, kind, workItemId, harnessUsed,
       }).then((result) => {
         if (result && result.threadId) console.log(`ADO thread ${result.threadId} created`);
       }).catch((e) => {
@@ -2084,7 +2157,7 @@ const commands = {
 
     try {
       const result = ghComment.postPrComment({
-        repo, prNumber, body, agentId, kind, workItemId,
+        repo, prNumber, body, agentId, kind, workItemId, harnessUsed,
       });
       if (result.output) console.log(result.output);
     } catch (e) {
@@ -2223,6 +2296,8 @@ module.exports = {
   _readDispatchPid: readDispatchPid,
   _normalizeSessionBranch: normalizeSessionBranch,
   _dispatchSessionBranch: dispatchSessionBranch,
+  // P-7a3c9e21 — harness-flag resolver exported for CLI-threading tests.
+  _resolveHarnessUsedForComment: resolveHarnessUsedForComment,
   // W-mpcyvff6000pf828 (#2653) — heartbeat writer + factory exported for tests
   _writeHeartbeatNow: writeHeartbeatNow,
   _createHeartbeatInterval: createHeartbeatInterval,

package/engine/github.js

@@ -633,11 +633,11 @@ async function forEachActiveGhPr(config, callback) {
       if (updated) {
         // Also update title/author/branch if still placeholder
         const currentTitle = pr.title || '';
-        if (!currentTitle || currentTitle.includes('polling...') || pr.agent === 'human' || pr.description === undefined) {
+        if (shared.isPlaceholderPrTitle(currentTitle) || pr.agent === 'human' || pr.description === undefined) {
           const prData = await ghApi(`/pulls/${prNum}`, slug);
           if (prData) {
             const latestTitle = pr.title || '';
-            if (!latestTitle || latestTitle.includes('polling...') || /[{}"\[\]]/.test(latestTitle) || /^[0-9a-f-]{8,}$/i.test(latestTitle)) {
+            if (shared.isPlaceholderPrTitle(latestTitle)) {
               pr.title = (prData.title || latestTitle).slice(0, 120);
             }
             if (pr.description === undefined) pr.description = (prData.body || '').slice(0, 500);
@@ -752,10 +752,7 @@ async function pollPrStatus(config) {
     // stay stuck on "PR #N (polling...)" forever. `prData` is already in
     // hand from line 622 — no extra API call needed.
     const currentTitleForBackfill = pr.title || '';
-    if (!currentTitleForBackfill
-        || currentTitleForBackfill.includes('polling...')
-        || /[{}"\[\]]/.test(currentTitleForBackfill)
-        || /^[0-9a-f-]{8,}$/i.test(currentTitleForBackfill)) {
+    if (shared.isPlaceholderPrTitle(currentTitleForBackfill)) {
       if (prData.title) {
         const nextTitle = String(prData.title).slice(0, 120);
         if (pr.title !== nextTitle) {

package/engine/shared.js

@@ -6553,6 +6553,32 @@ function findPrRecord(prs, prRef, project = null) {
   return numberMatches.length === 1 ? numberMatches[0] : null;
 }
 
+// Issue #289: single source of truth for "is this stored PR title a
+// placeholder/fallback that should be backfilled from the live platform
+// title on the next poll?". Recognizes:
+//   - empty / missing titles
+//   - the link-time "...(polling...)" placeholder
+//   - serialized-JSON / agent-output leakage (contains {}"[] chars)
+//   - bare hex/uuid-ish ids (>= 8 hex/dash chars)
+//   - the fallback WRITER shapes "PR created by <agent>" (engine/lifecycle.js)
+//     and bare "PR #<n>" (engine/ado.js central poller)
+// The WRITER (engine/lifecycle.js) and the DETECTORS (engine/github.js,
+// engine/ado.js) MUST agree — route every site through this helper so they
+// cannot drift apart again (the github poller previously never backfilled a
+// frozen "PR created by Ripley" title because its detector didn't know the shape).
+function isPlaceholderPrTitle(title) {
+  const t = typeof title === 'string'
+    ? title.trim()
+    : (title == null ? '' : String(title).trim());
+  if (!t) return true;
+  if (t.includes('polling...')) return true;
+  if (/[{}"\[\]]/.test(t)) return true;
+  if (/^[0-9a-f-]{8,}$/i.test(t)) return true;
+  if (/^PR created by /i.test(t)) return true;
+  if (/^PR #\d+$/i.test(t)) return true;
+  return false;
+}
+
 function snapshotPrRecord(pr) {
   if (pr === undefined) return undefined;
   return JSON.parse(JSON.stringify(pr));
@@ -8834,6 +8860,7 @@ module.exports = {
   isAdoPrScopeCompatible,
   getCanonicalPrId,
   findPrRecord,
+  isPlaceholderPrTitle,
   snapshotPrRecord,
   applyPrFieldDelta,
   normalizePrRecord,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2228",
+  "version": "0.1.2229",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/playbooks/shared-rules.md

@@ -153,7 +153,11 @@ Copyable worked example:
 
 Entries you report are **cross-checked** against what the engine propagated into your worktree and annotated `grounded: true | false` — never dropped — so a `grounded: false` entry surfaces a discrepancy for a human rather than being hidden. Full contract: `docs/harness-transparency.md`.
 
-When you author a **PR review / fix summary comment** (GitHub `minions pr comment` / `gh pr comment`, or Azure DevOps `az repos pr comment`), fold the same harness footprint into the body as a collapsible section so reviewers see which skills / MCPs / docs informed the change. Render it **identically on both hosts** — append this exact `<details>` block at the end of your comment body (omit it entirely when you used no affordances):
+When you author a **PR review / fix summary comment**, the same harness footprint belongs in the comment body as a collapsible "Harnesses used" section so reviewers see which skills / MCPs / docs informed the change.
+
+**Preferred — `minions pr comment` (GitHub and Azure DevOps `--host ado`): do NOT hand-render the section.** Write your `harnessUsed` record — the same `{ skills, mcpServers, commands, docs }` shape as the completion field above — to a JSON file and pass `--harness-file <path>` (or inline via `--harness-json <json>`). The shared builder (`engine/comment-format.js#buildHarnessUsedSection`, consumed by both `engine/gh-comment.js` and `engine/ado-comment.js`) folds the byte-identical `<details>` section into the body for you, so agent-authored and engine-authored comments match. Each entry is cross-checked against the harness manifest the engine propagated into your worktree and annotated `grounded: true | false` (never dropped); a `grounded: false`, ⚠️-marked bullet means **the engine couldn't confirm that affordance against the propagated manifest — not that you did anything wrong**.
+
+**Raw fallbacks only — `gh pr comment` / `az repos pr comment` / ADO REST:** these bypass the CLI chokepoint, so you MUST hand-render the section yourself. Render it **identically on both hosts** — append this exact `<details>` block at the end of your comment body (omit it entirely when you used no affordances):
 
 ```markdown
 <details>
@@ -167,7 +171,7 @@ When you author a **PR review / fix summary comment** (GitHub `minions pr commen
 </details>
 ```
 
-One bullet per affordance, in the order skills → MCP servers → commands → docs; `N` is the bullet count. This is the human-readable mirror of your `harnessUsed` completion field — keep the two consistent. The engine renders the byte-identical section via `engine/comment-format.js#buildHarnessUsedSection` when it composes a comment, so agent-authored and engine-authored sections match.
+One bullet per affordance, in the order skills → MCP servers → commands → docs; `N` is the bullet count. Whether the CLI folds it in or you hand-render it on a raw fallback, the section is the human-readable mirror of your `harnessUsed` completion field — keep the two consistent.
 
 ## Minions API access