@yemi33/minions 0.1.2164 → 0.1.2166

package/dashboard.js

@@ -7861,84 +7861,29 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const body = await readBody(req);
       if (!body.path) return jsonReply(res, 400, { error: 'path required' });
 
-      // SEC-05: validate path (must be a git repo, unless caller supplies
-      // allowNonRepo + a valid single-use confirmation token). Runs BEFORE any
-      // mutation of config.json so a rejected path leaves no side effects.
-      let target;
+      // W-mq8li79a000889fa: route through projects.addProject so dashboard
+      // and CLI share the same SEC-validate + auto-discover + REST-fallback
+      // + fail-closed gate (rejects ADO links missing repositoryId).
+      const { addProject } = require('./engine/projects');
+      let result;
       try {
-        target = shared.validateProjectPath(body.path, {
+        result = await addProject(body.path, {
           allowNonRepo: body.allowNonRepo === true,
           confirmToken: body.confirmToken,
           isValidToken: _consumeProjectConfirmToken,
+          name: body.name,
+          worktreeMode: body.worktreeMode,
+          observeAuthors: Array.isArray(body.observeAuthors) ? body.observeAuthors : undefined,
         });
       } catch (e) {
         return jsonReply(res, e.statusCode || 400, {
           error: e.message,
           ...(e.needsConfirmation ? { needsConfirmation: true } : {}),
+          ...(e.missing ? { missing: e.missing } : {}),
+          ...(e.code ? { code: e.code } : {}),
         });
       }
 
-      // Check if already linked under the config lock so concurrent dashboard
-      // adds cannot both pass the preflight check and then clobber config.json.
-      let alreadyLinked = false;
-      mutateDashboardConfig(config => {
-        if (!Array.isArray(config.projects)) config.projects = [];
-        alreadyLinked = config.projects.some(p => shared.sameResolvedPath(p.localPath, target));
-        return config;
-      });
-      if (alreadyLinked) {
-        return jsonReply(res, 400, { error: 'Project already linked at ' + target });
-      }
-
-      // Auto-discover from git repo. Shared with minions.js so CLI and dashboard
-      // handle ADO URL variants and repository GUID enrichment consistently.
-      const detected = projectDiscovery.discoverProjectMetadata(target);
-      if (!detected.name) detected.name = path.basename(target);
-      const description = detected.description || '';
-
-      const rawName = body.name || detected.name;
-
-      // SEC-04: validate project name — rejects path traversal, shell
-      // metacharacters, whitespace, overly long names. Runs BEFORE any
-      // mutation of config.json. Auto-detected names (from package.json /
-      // directory basename) also go through this check so a maliciously
-      // named repo on disk can't inject metacharacters either.
-      let name;
-      try {
-        name = shared.validateProjectName(rawName);
-      } catch (e) {
-        return jsonReply(res, e.statusCode || 400, { error: e.message });
-      }
-
-      const project = projectDiscovery.buildProjectEntry({
-        name, description, localPath: target,
-        repoHost: detected.repoHost || 'github',
-        repositoryId: detected.repositoryId || '',
-        org: detected.org || '',
-        project: detected.project || '',
-        repoName: detected.repoName || name,
-        mainBranch: detected.mainBranch || 'main',
-        prUrlBase: detected.prUrlBase,
-        // P-a3f9b201: thread worktreeMode from POST body. buildProjectEntry
-        // validates via shared.validateWorktreeMode — unknown values bubble
-        // up as HTTP 400 below.
-        worktreeMode: body.worktreeMode,
-      });
-
-      // Create centralized project state files.
-      shared.ensureProjectStateFiles(project);
-
-      let duplicate = false;
-      mutateDashboardConfig(config => {
-        if (!Array.isArray(config.projects)) config.projects = [];
-        if (config.projects.some(p => shared.sameResolvedPath(p.localPath, target))) {
-          duplicate = true;
-          return config;
-        }
-        config.projects.push(project);
-        return config;
-      });
-      if (duplicate) return jsonReply(res, 400, { error: 'Project already linked at ' + target });
       reloadConfig(); // Update in-memory project list immediately
       warmProjectGitStatusCache(); // Probe the new project's git status in the background
       // includeSlow: PROJECTS lives in the slow-state cache (60s TTL); without
@@ -7946,7 +7891,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       // up to a minute after the add. Matches handleProjectsRemove's behavior.
       invalidateStatusCache({ includeSlow: true });
 
-      return jsonReply(res, 200, { ok: true, name, path: target, detected });
+      return jsonReply(res, 200, {
+        ok: true,
+        name: result.project.name,
+        path: result.path,
+        detected: result.detected,
+      });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 

package/docs/deprecated-process.md

@@ -0,0 +1,69 @@
+# Deprecation tracker — schema and audit process
+
+Source of truth: [`docs/deprecated.json`](./deprecated.json) — array of deprecation entries the `cleanup-deprecated` skill walks weekly.
+
+Each entry documents one deprecated symbol / config field / endpoint, why it
+exists, when (and under what signal) it is safe to remove, and which tests
+pin its contract until the removal lands.
+
+## Common fields
+
+The schema is loose — entries grow fields as their gating story matures. The
+following are all optional unless called out as required.
+
+- `id` — **required**, kebab-case unique identifier (e.g. `completion-fallback-parsers`).
+- `description` / `reason` — free-form prose explaining what is deprecated and why.
+- `file` / `location` / `code` — pointer(s) to the deprecated symbol(s). `code` is
+  the structured form: an array of `{ file, lines, note }` objects.
+- `lines` — comma-separated string of line numbers (drift-prone; cross-check before
+  acting).
+- `deprecated` / `targetRemovalDate` — calendar dates (YYYY-MM-DD) marking when
+  the entry was registered and when it may be removed. `targetRemovalDate: null`
+  signals a non-calendar gate (telemetry / signal-based).
+- `removalGate` — prose describing the signal that must clear before removal.
+- `notes` — free-form post-removal scope or rollout caveats.
+
+## Counter-gated entries (telemetry sentinels)
+
+When the removal gate is "this counter must read 0 across a sweep window," the
+entry uses these fields:
+
+- `telemetryGate` — string referencing the metrics counter that must read zero.
+- `sweepWindowDays` — positive integer (window length in days).
+- `sweepStartDate` — `YYYY-MM-DD` window start.
+- `enforcingTest` / `enforcingSweepWindowTest` — paths to the unit tests that
+  pin the gate contract.
+
+## Static call-site audit fields (P-c5d9e7b4)
+
+Counter-gated entries also opt in to the static call-site audit
+(`test/unit/deprecated-call-site-audit.test.js`). The audit enumerates live
+call sites of the entry's symbols across `engine/`, `dashboard/`, and the
+root-level `.js` files, then asserts every discovered call site is declared
+in either `removalSites` or `allowedCallers`.
+
+- `symbols` — **required for the audit to run**. Array of bare identifier
+  strings (e.g. `["parseStructuredCompletion", "parseCompletionFieldSummary"]`).
+  The audit builds a `\b<symbol>\s*\(` regex per name and skips matches that
+  sit immediately after the `function` keyword (i.e. it does not count the
+  definition itself as a caller). If `symbols` is missing or empty, the audit
+  fails the entry — there is no fallback parse of `description`.
+- `removalSites` — array of `{ file, line, symbol?, reason? }` objects listing
+  the call sites that WILL be removed when the deprecation gate clears (the
+  "expected, planned" callers). Paths are forward-slash relative to the repo
+  root.
+- `allowedCallers` — array of `{ site, reason }` objects (or
+  `{ file, line, reason }` — both shapes are accepted) listing call sites that
+  are intentionally preserved past the gate (e.g. a sibling deprecation that
+  will retire separately). Defaults to `[]` when absent.
+
+The audit assertion is `discoveredCallers ⊆ (removalSites ∪ allowedCallers)`.
+On failure, the assertion message names every unexpected `file:line` so the
+audit author can immediately classify each one as a new `removalSites` entry
+or a new `allowedCallers` entry.
+
+Entries WITHOUT a `telemetryGate` field are skipped by the audit — calendar-
+gated entries (e.g. `qa-json-sidecars`) and signal-gated entries that don't
+hang on a counter (e.g. `config-claude-binary-override`) don't carry the
+`symbols` / `removalSites` / `allowedCallers` triple and are not enforced by
+the static audit. Add them later if the gate evolves into a counter sentinel.

package/docs/deprecated.json

@@ -34,7 +34,14 @@
     "sweepRationale": "14 days matches the dead-code audit cadence (one full weekly audit cycle plus a buffer week). Window restarted on 2026-06-11 (= merge_date(P-a7b2c1d9) + 1 day, anchor commit eb544aa80dbd64c87b78ad08a17ca3560e627094 merged 2026-06-10T18:04:12Z) because the original 2026-05-27 window was invalidated: the engine/timeout.js caller of parseStructuredCompletion (commit 0f4b9787, 2026-04-30) predated the telemetry counter (commit cea61119, 2026-05-13), so the hidden caller was never instrumented and a zero reading proved nothing. P-a7b2c1d9 removed that hidden caller; the new window measures only callers that the counter actually instruments. Policy decision pending confirmation in open-question #1 of the 2026-05-27 Bug Audit Review meeting conclusion — if the human teammate prefers a different cadence, repin this field and the matching enforcingSweepWindowTest fixture.",
     "enforcingTest": "test/unit/completion-fallback-telemetry.test.js:217-234",
     "enforcingSweepWindowTest": "test/unit/completion-fallback-sweep-window.test.js",
-    "notes": "Do NOT set removedAt until telemetry confirms zero usage across the sweepWindowDays from sweepStartDate. The follow-up code-removal PR (dropping parseStructuredCompletion at engine/lifecycle.js:3410, parseCompletionFieldSummary at :3608, and the gated fallback at :4675-4700) is dispatched separately once the window is observed clean."
+    "symbols": ["parseStructuredCompletion", "parseCompletionFieldSummary"],
+    "removalSites": [
+      { "file": "engine/lifecycle.js", "line": 4675, "symbol": "parseStructuredCompletion", "reason": "Gated fallback at engine/lifecycle.js:4675-4700 — removed in the same follow-up PR that drops the parser definitions." },
+      { "file": "engine/lifecycle.js", "line": 4676, "symbol": "parseCompletionFieldSummary", "reason": "Gated fallback at engine/lifecycle.js:4675-4700 — removed in the same follow-up PR that drops the parser definitions." }
+    ],
+    "allowedCallers": [],
+    "schemaRef": "docs/deprecated-process.md (see 'Static call-site audit fields')",
+    "notes": "Do NOT set removedAt until telemetry confirms zero usage across the sweepWindowDays from sweepStartDate. The follow-up code-removal PR (dropping parseStructuredCompletion at engine/lifecycle.js:3410, parseCompletionFieldSummary at :3608, and the gated fallback at :4675-4700) is dispatched separately once the window is observed clean. The symbols/removalSites/allowedCallers triple is enforced by test/unit/deprecated-call-site-audit.test.js — see docs/deprecated-process.md for the schema."
   },
   {
     "id": "config-claude-binary-override",

package/engine/project-discovery.js

@@ -195,6 +195,61 @@ function runAzJson(execFileSync, args, timeoutMs) {
   }));
 }
 
+// W-mq8li79a000889fa — official ADO REST endpoint for repo lookup.
+// Matches engine/ado.js#resolveAdoBuildRepositoryGuid (the canonical
+// PR-poll path). Path-style encoding mirrors that helper so a project
+// named with reserved chars (e.g. "Project With Spaces") routes the
+// same way at link time as at poll time. The repo segment is URL-
+// encoded — ADO accepts either the repo GUID or repo name here.
+function _buildAdoRepoLookupUrl({ orgUrl, project, repoName }) {
+  return `${orgUrl}/${encodeURIComponent(project)}/_apis/git/repositories/${encodeURIComponent(repoName)}?api-version=7.1`;
+}
+
+// W-mq8li79a000889fa — REST-based GUID resolver. Returns the canonical
+// repo metadata when ADO responds 200 + JSON; returns null on any
+// failure (auth, network, 404, HTML redirect). Fail-closed semantics
+// are the caller's responsibility — discoverProjectMetadataAsync calls
+// this AFTER `az repos show/list` to fill in the GUID when the CLI is
+// unavailable (typical agent box without Azure CLI installed).
+//
+// Token acquisition uses engine/ado-token.js#acquireAdoToken (az CLI
+// then azureauth fallback). Tests inject `options.fetch` and
+// `options.acquireAdoToken` directly.
+async function resolveAdoRemoteMetadataViaRest(remote, options = {}) {
+  if (!remote || !remote.orgUrl || !remote.project || !remote.repoName) return null;
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') return null;
+  let acquireToken = options.acquireAdoToken;
+  if (typeof acquireToken !== 'function') {
+    try { acquireToken = require('./ado-token').acquireAdoToken; }
+    catch { return null; }
+  }
+  let token;
+  try {
+    const result = await acquireToken({});
+    token = result && result.token;
+  } catch { return null; }
+  if (!token) return null;
+
+  const url = _buildAdoRepoLookupUrl(remote);
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      method: 'GET',
+      headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
+    });
+  } catch { return null; }
+  if (!res || !res.ok) return null;
+  let text;
+  try { text = await res.text(); } catch { return null; }
+  if (!text || text.trimStart().startsWith('<')) return null;
+  let data;
+  try { data = JSON.parse(text); } catch { return null; }
+  const normalized = normalizeAzRepoResult(data, remote);
+  if (!normalized || !String(normalized.repositoryId || '').trim()) return null;
+  return normalized;
+}
+
 function resolveAdoRemoteMetadata(remote, options = {}) {
   if (!remote) return null;
   const execFileSync = options.execFileSync || defaultExecFileSync;
@@ -330,6 +385,42 @@ function discoverProjectMetadata(targetDir, options = {}) {
   return result;
 }
 
+// W-mq8li79a000889fa — async wrapper that runs the sync `az`-based
+// discovery first, then falls back to the official ADO REST endpoint
+// (via engine/ado-token.js + globalThis.fetch) when the remote is ADO
+// but no repositoryId was resolved. Non-ADO remotes are returned
+// unchanged. Failure to resolve the GUID via REST leaves
+// `repositoryId` empty — callers (engine/projects.js#addProject) MUST
+// fail closed if the linked project ends up without a GUID.
+async function discoverProjectMetadataAsync(targetDir, options = {}) {
+  const detected = discoverProjectMetadata(targetDir, options);
+  if (!detected || detected.repoHost !== 'ado') return detected;
+  if (String(detected.repositoryId || '').trim()) return detected;
+  // ADO remote without GUID — try official REST endpoint as a fallback.
+  // discoverProjectMetadata always populates org/orgUrl/project/repoName
+  // for ADO remotes (via parseAdoRemoteUrl), so this is safe to call.
+  const parsedRemote = {
+    org: detected.org,
+    orgUrl: detected.orgUrl,
+    project: detected.project,
+    repoName: detected.repoName,
+    repoHost: 'ado',
+    remoteUrl: detected.remoteUrl,
+    prUrlBase: detected.prUrlBase,
+    collection: detected.collection || '',
+    repositoryId: '',
+  };
+  const restMeta = await resolveAdoRemoteMetadataViaRest(parsedRemote, options);
+  if (restMeta && String(restMeta.repositoryId || '').trim()) {
+    Object.assign(detected, restMeta);
+    if (!Array.isArray(detected._found)) detected._found = [];
+    if (!detected._found.includes('Azure DevOps repository metadata (REST)')) {
+      detected._found.push('Azure DevOps repository metadata (REST)');
+    }
+  }
+  return detected;
+}
+
 function buildPrUrlBase({ repoHost, org, project, repoName, prUrlBase }) {
   if (prUrlBase) return prUrlBase;
   if (repoHost === 'github') {
@@ -341,7 +432,7 @@ function buildPrUrlBase({ repoHost, org, project, repoName, prUrlBase }) {
   return '';
 }
 
-function buildProjectEntry({ name, description, localPath, repoHost, repositoryId, org, project, repoName, mainBranch, prUrlBase, worktreeMode }) {
+function buildProjectEntry({ name, description, localPath, repoHost, repositoryId, org, project, repoName, mainBranch, prUrlBase, worktreeMode, observeAuthors }) {
   const safeName = (name || 'project').replace(/[^a-zA-Z0-9._-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '').slice(0, 60) || 'project';
   const host = repoHost || 'github';
   const isAdo = host === 'ado';
@@ -368,6 +459,17 @@ function buildProjectEntry({ name, description, localPath, repoHost, repositoryI
     },
   };
   if (resolvedWorktreeMode !== undefined) entry.worktreeMode = resolvedWorktreeMode;
+  // W-mq8li79a000889fa — observeAuthors is the canonical list of author
+  // identifiers consumed by the `ado-author-prs` watch (and any future
+  // author-scoped watch). Currently only meaningful for ADO projects —
+  // the GitHub flow uses watch targets directly. Stored as an array of
+  // strings; only persisted when explicitly supplied so existing
+  // projects don't gain an empty field on rewrites.
+  if (Array.isArray(observeAuthors) && observeAuthors.length > 0) {
+    entry.observeAuthors = observeAuthors
+      .map(v => String(v || '').trim())
+      .filter(Boolean);
+  }
   return entry;
 }
 
@@ -391,7 +493,9 @@ module.exports = {
   parseAdoRemoteUrl,
   parseGitHubRemoteUrl,
   resolveAdoRemoteMetadata,
+  resolveAdoRemoteMetadataViaRest,
   discoverProjectMetadata,
+  discoverProjectMetadataAsync,
   buildPrUrlBase,
   buildProjectEntry,
   buildScanResult,

package/engine/projects.js

@@ -9,8 +9,16 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 const dispatch = require('./dispatch');
+const projectDiscovery = require('./project-discovery');
 const { MINIONS_DIR } = shared;
 
+function _httpError(status, message, extra) {
+  const err = new Error(message);
+  err.statusCode = status;
+  if (extra) Object.assign(err, extra);
+  return err;
+}
+
 function _sameProjectName(a, b) {
   return String(a || '').toLowerCase() === String(b || '').toLowerCase();
 }
@@ -429,4 +437,134 @@ function removeProject(target, options = {}) {
   return summary;
 }
 
-module.exports = { removeProject };
+// ─── Project Add (W-mq8li79a000889fa) ────────────────────────────────────────
+// Centralized project link helper used by both /api/projects/add (dashboard)
+// and `minions add <path>` (CLI). Mirrors removeProject's "single source of
+// truth" role so add semantics are identical regardless of entry point.
+//
+// Fail-closed contract for Azure DevOps projects:
+//   - The linked entry MUST end up with a real repositoryId (GUID). The
+//     poller, watches, and conflict-resolution surfaces all key on it; an
+//     empty value silently breaks downstream automation.
+//   - Resolution path is `az repos show` → `az repos list` → official ADO
+//     REST endpoint (`/_apis/git/repositories/{repo}?api-version=7.1`).
+//   - When ALL three paths fail to surface a GUID, throw a 4xx-shaped Error
+//     and DO NOT persist a partial project entry to config.json. Callers
+//     translate `err.statusCode` (default 400) + `err.message` to their
+//     transport (HTTP body / CLI stderr).
+//
+// observeAuthors:
+//   - Optional array of identifiers (UPNs, display names) the `ado-author-prs`
+//     watch will surface PRs from. Stored on the project entry so the watch
+//     can validate the project shape up-front instead of failing at evaluate
+//     time. Non-ADO projects ignore this field (watch is ADO-only today).
+//
+// Concurrency:
+//   - Config is mutated under mutateJsonFileLocked so a concurrent CLI add
+//     and dashboard add cannot both pass the pre-check and double-insert.
+function assertProjectLinkOk(project) {
+  if (!project || typeof project !== 'object') {
+    throw _httpError(400, 'Invalid project entry: must be an object');
+  }
+  const host = String(project.repoHost || 'github').toLowerCase();
+  if (host !== 'ado') return; // GitHub / generic projects have no required GUID
+
+  const missing = [];
+  if (!String(project.repositoryId || '').trim()) missing.push('repositoryId');
+  if (!String(project.adoOrg || '').trim()) missing.push('adoOrg');
+  if (!String(project.adoProject || '').trim()) missing.push('adoProject');
+  if (!String(project.repoName || '').trim()) missing.push('repoName');
+  if (missing.length === 0) return;
+
+  const label = project.name || project.localPath || '<unknown>';
+  const hint = missing.includes('repositoryId')
+    ? ' Resolve via Azure CLI (`az login` + `az repos show`) or by linking from a host where the ADO REST API is reachable.'
+    : '';
+  throw _httpError(400,
+    `ADO project "${label}" missing required field(s): ${missing.join(', ')}.${hint}`,
+    { missing, code: 'PROJECT_LINK_INVALID_ADO' });
+}
+
+async function addProject(target, options = {}) {
+  const inputPath = typeof target === 'string' ? target : (target && target.path);
+  if (!inputPath || typeof inputPath !== 'string') {
+    throw _httpError(400, 'addProject: target path required');
+  }
+
+  // 1. Validate path (must exist + be a git repo OR caller opts in via
+  //    allowNonRepo + confirmToken — same contract as the dashboard handler).
+  const resolved = shared.validateProjectPath(inputPath, {
+    allowNonRepo: options.allowNonRepo === true,
+    confirmToken: options.confirmToken,
+    isValidToken: options.isValidToken,
+  });
+
+  // 2. Pre-flight duplicate check OUTSIDE the lock so the common case
+  //    (already-linked) returns a clean 400 without churning the config file.
+  //    Resolve config path through `shared.MINIONS_DIR` (fresh on each call)
+  //    so tests that swap MINIONS_DIR via createTestMinionsDir() see the
+  //    right path even when projects.js itself isn't isolated.
+  const configPath = path.join(shared.MINIONS_DIR, 'config.json');
+  const existingConfig = shared.safeJson(configPath) || { projects: [] };
+  const existingProjects = Array.isArray(existingConfig.projects) ? existingConfig.projects : [];
+  if (existingProjects.some(p => shared.sameResolvedPath(p.localPath, resolved))) {
+    throw _httpError(400, `Project already linked at ${resolved}`);
+  }
+
+  // 3. Discover metadata. Async path includes the official ADO REST fallback
+  //    for repositoryId when `az` CLI isn't available — see
+  //    project-discovery.js#discoverProjectMetadataAsync.
+  const detected = await projectDiscovery.discoverProjectMetadataAsync(resolved, options);
+  if (!detected.name) detected.name = path.basename(resolved);
+
+  // 4. Validate name (rejects shell metacharacters, path separators, …).
+  const rawName = options.name || detected.name;
+  const name = shared.validateProjectName(rawName);
+
+  // 5. Build entry.
+  const project = projectDiscovery.buildProjectEntry({
+    name,
+    description: options.description !== undefined ? options.description : (detected.description || ''),
+    localPath: resolved,
+    repoHost: detected.repoHost || 'github',
+    repositoryId: detected.repositoryId || '',
+    org: detected.org || '',
+    project: detected.project || '',
+    repoName: detected.repoName || name,
+    mainBranch: detected.mainBranch || 'main',
+    prUrlBase: detected.prUrlBase,
+    worktreeMode: options.worktreeMode,
+    observeAuthors: Array.isArray(options.observeAuthors) ? options.observeAuthors : undefined,
+  });
+
+  // 6. Fail-closed gate. AFTER buildProjectEntry — buildProjectEntry never
+  //    re-resolves metadata, so this check sees the same shape the engine
+  //    will. Throws statusCode=400 with `missing[]` populated.
+  assertProjectLinkOk(project);
+
+  // 7. Ensure project state files (projects/<name>/...).
+  shared.ensureProjectStateFiles(project);
+
+  // 8. Persist under config lock. Re-check inside the lock so a concurrent
+  //    add can't insert a duplicate between our pre-check and the write.
+  let duplicate = false;
+  shared.mutateJsonFileLocked(configPath, (config) => {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) config = { projects: [], agents: {}, engine: {} };
+    if (!Array.isArray(config.projects)) config.projects = [];
+    if (config.projects.some(p => shared.sameResolvedPath(p.localPath, resolved))) {
+      duplicate = true;
+      return config;
+    }
+    config.projects.push(project);
+    return config;
+  }, { defaultValue: { projects: [], agents: {}, engine: {} }, skipWriteIfUnchanged: true });
+
+  if (duplicate) throw _httpError(400, `Project already linked at ${resolved}`);
+
+  return { ok: true, project, detected, path: resolved };
+}
+
+module.exports.assertProjectLinkOk = assertProjectLinkOk;
+module.exports.addProject = addProject;
+
+module.exports.removeProject = removeProject;

package/minions.js

@@ -129,12 +129,39 @@ async function addProject(targetDir) {
   const repositoryId = await ask('Repository ID (GUID, optional)', detected.repositoryId || '');
   const mainBranch = await ask('Main branch', detected.mainBranch || 'main');
 
+  // W-mq8li79a000889fa: prompt for observed authors on ADO projects so the
+  // ado-author-prs watch plugin has a configured author list to track.
+  // Empty string -> no observeAuthors persisted (back-compat).
+  let observeAuthors;
+  if (String(repoHost || '').toLowerCase() === 'ado') {
+    const raw = await ask('Observe authors (comma-separated emails, optional)', '');
+    const list = String(raw || '').split(',').map(s => s.trim()).filter(Boolean);
+    if (list.length > 0) observeAuthors = list;
+  }
+
   rl.close();
 
   const projectEntry = buildProjectEntry({
     name, description, localPath: target, repoHost, repositoryId, org, project, repoName, mainBranch,
     prUrlBase: detected.prUrlBase,
+    observeAuthors,
   });
+
+  // W-mq8li79a000889fa: fail-closed gate. ADO projects must have repositoryId
+  // (the engine's ADO REST endpoints take a repo GUID, not a name) plus org +
+  // project + repoName for the dashboard's PR routing to work. Surface the
+  // missing fields up front rather than letting the CLI silently persist a
+  // broken project.
+  try {
+    require('./engine/projects').assertProjectLinkOk(projectEntry);
+  } catch (e) {
+    console.log(`\n  Error: ${e.message}`);
+    if (Array.isArray(e.missing) && e.missing.length > 0) {
+      console.log(`  Missing required field(s): ${e.missing.join(', ')}`);
+    }
+    process.exit(1);
+  }
+
   shared.ensureProjectStateFiles(projectEntry);
   config.projects.push(projectEntry);
   saveConfig(config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2164",
+  "version": "0.1.2166",
   "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"