ralph-hero-mcp-server 2.5.118 → 2.5.120

package/dist/index.js

@@ -16,6 +16,7 @@ import { FieldOptionCache } from "./lib/cache.js";
 import { createDebugLogger, wrapServerToolWithLogging } from "./lib/debug-logger.js";
 import { toolSuccess, resolveProjectOwner } from "./types.js";
 import { resolveRepoFromProject } from "./lib/helpers.js";
+import { detectOrphanRepoIssues } from "./lib/health.js";
 import { registerProjectTools } from "./tools/project-tools.js";
 import { registerIssueTools } from "./tools/issue-tools.js";
 import { registerRelationshipTools } from "./tools/relationship-tools.js";
@@ -188,7 +189,7 @@ function initGitHubClient(debugLogger) {
  */
 function registerCoreTools(server, client) {
     // Health check tool - comprehensive validation of auth, repo, project, and fields
-    server.tool("ralph_hero__health_check", "Validate GitHub API connectivity, token permissions, repo access, project access, and required fields", {}, async () => {
+    server.tool("ralph_hero__health_check", "Validate GitHub API connectivity, token permissions, repo access, project access, and required fields. Also surfaces repo-scope mismatch via the `orphanRepoIssues` field when OPEN issues exist in the repo but are NOT on the configured project board (such issues are invisible to discovery tools like next_actions, list_issues, pipeline_dashboard, project_hygiene). The field is omitted entirely when the board contains every OPEN repo issue. Shape when present: `{ count, repoOpen, boardItems, sample: number[], note }` — `sample` is up to 10 orphan issue numbers (ascending) for diagnostic display.", {}, async () => {
         const checks = {};
         // 1. Auth check (repo token)
         try {
@@ -297,6 +298,26 @@ function registerCoreTools(server, client) {
                 detail: "RALPH_GH_PROJECT_NUMBER not set",
             };
         }
+        // 5. Orphan repo issues check — only runs when both repo and project
+        // access succeeded above. Failures here are non-fatal: orphan detection
+        // is informational and shouldn't downgrade the overall health status,
+        // because the underlying access checks already capture the real failure
+        // mode (broken token, missing project, etc.).
+        let orphanRepoIssues = null;
+        if (checks.repoAccess?.status === "ok" &&
+            checks.projectAccess?.status === "ok" &&
+            client.config.owner &&
+            client.config.repo &&
+            projOwner &&
+            projNum) {
+            try {
+                orphanRepoIssues = await detectOrphanRepoIssues(client, client.config.owner, client.config.repo, projOwner, projNum);
+            }
+            catch (e) {
+                // Non-fatal — log via stderr but don't fail health_check.
+                console.error(`[ralph-hero] Orphan repo issues check failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
         // Token source detection — re-derive which env vars resolved
         const repoTokenSource = resolveEnv("RALPH_GH_REPO_TOKEN")
             ? "RALPH_GH_REPO_TOKEN"
@@ -327,6 +348,9 @@ function registerCoreTools(server, client) {
                     ? `Repo operations use ${repoTokenSource}, project operations use ${projectTokenSource}`
                     : `Both repo and project operations use ${repoTokenSource}`,
             },
+            // Omit the field entirely when there are no orphans, per the field's
+            // contract (`null` from `detectOrphanRepoIssues` means "clean board").
+            ...(orphanRepoIssues ? { orphanRepoIssues } : {}),
         });
     });
 }

package/dist/lib/dashboard.js

@@ -5,12 +5,13 @@
  * I/O (GraphQL fetching) lives in tools/dashboard-tools.ts.
  */
 import { STATE_ORDER, LOCK_STATES, TERMINAL_STATES, HUMAN_STATES, } from "./workflow-states.js";
+import { ARCHIVE_AGE_DAYS, CRITICAL_STUCK_HOURS, RECENT_WINDOW_DAYS, STUCK_THRESHOLD_HOURS, } from "./thresholds.js";
 export const DEFAULT_HEALTH_CONFIG = {
-    stuckThresholdHours: 48,
-    criticalStuckHours: 96,
+    stuckThresholdHours: STUCK_THRESHOLD_HOURS,
+    criticalStuckHours: CRITICAL_STUCK_HOURS,
     wipLimits: {},
-    doneWindowDays: 7,
-    archiveThresholdDays: 14,
+    doneWindowDays: RECENT_WINDOW_DAYS,
+    archiveAgeDays: ARCHIVE_AGE_DAYS,
 };
 // ---------------------------------------------------------------------------
 // Priority helpers
@@ -282,13 +283,13 @@ const DAY_MS = 24 * 60 * 60 * 1000;
 /**
  * Compute archive eligibility stats from project items.
  *
- * - "Eligible for archive": Done/Canceled items stale beyond archiveThresholdDays
+ * - "Eligible for archive": Done/Canceled items stale beyond archiveAgeDays
  * - "Recently completed": Done/Canceled items within doneWindowDays
  * - Staleness computed from closedAt (preferred) or updatedAt (fallback)
  * - Zero additional API calls — works on already-fetched items.
  */
-export function computeArchiveStats(items, now, archiveThresholdDays, doneWindowDays) {
-    const thresholdMs = archiveThresholdDays * DAY_MS;
+export function computeArchiveStats(items, now, archiveAgeDays, doneWindowDays) {
+    const thresholdMs = archiveAgeDays * DAY_MS;
     const recentMs = doneWindowDays * DAY_MS;
     const eligible = [];
     let recentlyCompleted = 0;
@@ -317,7 +318,7 @@ export function computeArchiveStats(items, now, archiveThresholdDays, doneWindow
         eligibleForArchive: eligible.length,
         eligibleItems: eligible,
         recentlyCompleted,
-        archiveThresholdDays,
+        archiveAgeDays,
     };
 }
 // ---------------------------------------------------------------------------
@@ -437,7 +438,7 @@ export function buildIterationSection(items) {
 export function buildDashboard(items, config = DEFAULT_HEALTH_CONFIG, now = Date.now(), streams) {
     const phases = aggregateByPhase(items, now, config);
     const warnings = detectHealthIssues(phases, config);
-    const archive = computeArchiveStats(items, now, config.archiveThresholdDays, config.doneWindowDays);
+    const archive = computeArchiveStats(items, now, config.archiveAgeDays, config.doneWindowDays);
     // Per-project breakdown (only when items span multiple projects)
     const projectGroups = new Map();
     for (const item of items) {
@@ -580,7 +581,7 @@ export function formatMarkdown(data, issuesPerPhase = 10) {
         lines.push("");
         lines.push("## Archive Eligibility");
         lines.push("");
-        lines.push(`**Eligible for archive**: ${data.archive.eligibleForArchive} items (stale > ${data.archive.archiveThresholdDays} days in Done/Canceled)`);
+        lines.push(`**Eligible for archive**: ${data.archive.eligibleForArchive} items (stale > ${data.archive.archiveAgeDays} days in Done/Canceled)`);
         lines.push(`**Recently completed**: ${data.archive.recentlyCompleted} items`);
         if (data.archive.eligibleItems.length > 0) {
             lines.push("");
@@ -755,7 +756,7 @@ export function formatAscii(data) {
     }
     // Archive summary
     if (data.archive) {
-        lines.push(`Archive: ${data.archive.eligibleForArchive} eligible (threshold: ${data.archive.archiveThresholdDays}d), ${data.archive.recentlyCompleted} recent`);
+        lines.push(`Archive: ${data.archive.eligibleForArchive} eligible (threshold: ${data.archive.archiveAgeDays}d), ${data.archive.recentlyCompleted} recent`);
     }
     // Per-project breakdown (only for multi-project)
     if (data.projectBreakdowns &&

package/dist/lib/directions.js

@@ -28,12 +28,13 @@
  * PRs are scored separately and only merged into the final ranking.
  */
 import { LOCK_STATES, STATE_ORDER } from "./workflow-states.js";
+import { AGENT_BACKLOG_FALLBACK_PENALTY, LOCK_STALE_HOURS, PR_STALE_HOURS, RECENT_WINDOW_DAYS, STUCK_THRESHOLD_HOURS, } from "./thresholds.js";
 export const DEFAULT_RANK_CONFIG = {
     limit: 3,
-    stuckThresholdHours: 48,
-    lockStaleHours: 24,
-    treeRecentDoneDays: 7,
-    prStaleHours: 24,
+    stuckThresholdHours: STUCK_THRESHOLD_HOURS,
+    lockStaleHours: LOCK_STALE_HOURS,
+    treeRecentDoneDays: RECENT_WINDOW_DAYS,
+    prStaleHours: PR_STALE_HOURS,
     audience: "human",
 };
 // ---------------------------------------------------------------------------
@@ -68,13 +69,6 @@ const PR_REVIEW_REQUIRED_BOOST = -200;
  * waiting for the human's attention.
  */
 const HUMAN_NEEDED_UNBLOCK_BOOST = -150;
-/**
- * Penalty applied to Backlog / null-state items that surface only via the
- * `audience === "agent"` fallback. Large positive value ensures Backlog
- * fallback items always rank below any actionable-phase item — Backlog
- * surfaces only when the actionable pool is empty.
- */
-const AGENT_BACKLOG_FALLBACK_PENALTY = 100;
 /**
  * Per-estimate penalty applied when audience === "agent". Larger items
  * cost more (positive score), pushing them down the ranking so agent

package/dist/lib/health.js

@@ -0,0 +1,180 @@
+/**
+ * Health-check helpers — pure functions that probe the GitHub API for
+ * configuration drift between the project board and its underlying repo.
+ *
+ * `detectOrphanRepoIssues` compares the set of OPEN issues in the configured
+ * repo against the set of `type=ISSUE` items on the configured project
+ * board. Issues present in the repo but not on the board are "orphans" —
+ * they exist but are structurally invisible to the discovery tools
+ * (`next_actions`, `list_issues`, `pipeline_dashboard`, `project_hygiene`),
+ * which all read from the project board.
+ *
+ * Surfaced via `health_check` so users discover the mismatch without having
+ * to grep `gh issue list` against the board contents by hand.
+ */
+/**
+ * Maximum number of orphan issue numbers to include in the response sample.
+ * The sample is for diagnostic display only; the full set is summarized via `count`.
+ */
+export const ORPHAN_SAMPLE_LIMIT = 10;
+/**
+ * Page size used when paginating repo issues and project items.
+ *
+ * GitHub GraphQL caps `first:` at 100. Most projects fit comfortably in a
+ * handful of pages — pagination is implemented for correctness, not because
+ * every call hits it.
+ */
+const PAGE_SIZE = 100;
+/**
+ * Hard cap on pages walked when enumerating repo issues or project items.
+ * Defensive: prevents a runaway loop on a misconfigured giant repo.
+ */
+const MAX_PAGES = 20;
+/**
+ * Standard explanatory note attached to the orphan-repo-issues warning.
+ * Lifted to a constant so tests can assert against a single canonical string.
+ */
+export const ORPHAN_REPO_ISSUES_NOTE = "Issues exist in the repo that are not on the project board. They are " +
+    "invisible to discovery tools (next_actions, list_issues, pipeline_dashboard, " +
+    "project_hygiene). To make them visible, add them to the project or use " +
+    "'gh issue list' directly.";
+/**
+ * Fetch all OPEN issue numbers in the repo via paginated GraphQL.
+ *
+ * Returns `{ totalCount, numbers }`. `totalCount` is taken from the first
+ * page (it is constant across pages). `numbers` is the union of all
+ * `node.number` values walked.
+ */
+async function fetchRepoOpenIssueNumbers(client, owner, repo) {
+    const numbers = new Set();
+    let totalCount = 0;
+    let cursor = null;
+    let pages = 0;
+    while (pages < MAX_PAGES) {
+        const response = await client.query(`query($owner: String!, $repo: String!, $cursor: String, $first: Int!) {
+        repository(owner: $owner, name: $repo) {
+          issues(states: OPEN, first: $first, after: $cursor) {
+            totalCount
+            pageInfo { hasNextPage endCursor }
+            nodes { number }
+          }
+        }
+      }`, { owner, repo, cursor, first: PAGE_SIZE });
+        const page = response.repository?.issues;
+        if (!page)
+            break;
+        if (pages === 0)
+            totalCount = page.totalCount;
+        for (const node of page.nodes)
+            numbers.add(node.number);
+        if (!page.pageInfo.hasNextPage)
+            break;
+        cursor = page.pageInfo.endCursor;
+        pages += 1;
+    }
+    return { totalCount, numbers };
+}
+/**
+ * Fetch all `type=ISSUE` item numbers on the project board via paginated GraphQL.
+ *
+ * The query tries `user(login)` first, then falls back to `organization(login)`
+ * to handle both account types. PRs and DraftIssues are skipped — only true
+ * `Issue`-typed content with a `number` field is collected.
+ */
+async function fetchBoardIssueNumbers(client, projectOwner, projectNumber) {
+    const numbers = new Set();
+    let totalCount = 0;
+    let cursor = null;
+    let pages = 0;
+    // The project items query is identical across user/org owner — only the
+    // root selector changes. Build a closure that runs the same shape and
+    // tries both owner types on the first page.
+    const runQuery = async (cur) => {
+        for (const ownerType of ["user", "organization"]) {
+            try {
+                const res = await client.projectQuery(`query($owner: String!, $number: Int!, $cursor: String, $first: Int!) {
+            ${ownerType}(login: $owner) {
+              projectV2(number: $number) {
+                items(first: $first, after: $cursor) {
+                  totalCount
+                  pageInfo { hasNextPage endCursor }
+                  nodes {
+                    type
+                    content {
+                      __typename
+                      ... on Issue { number }
+                    }
+                  }
+                }
+              }
+            }
+          }`, { owner: projectOwner, number: projectNumber, cursor: cur, first: PAGE_SIZE });
+                const proj = res[ownerType]?.projectV2;
+                if (proj)
+                    return proj;
+            }
+            catch {
+                // Try next owner type
+            }
+        }
+        return null;
+    };
+    while (pages < MAX_PAGES) {
+        const proj = await runQuery(cursor);
+        if (!proj || !proj.items)
+            break;
+        if (pages === 0)
+            totalCount = proj.items.totalCount;
+        for (const node of proj.items.nodes) {
+            // Only count Issue-typed content. Type field is "ISSUE" but we double-check
+            // via __typename because draft-issue items can have type=DRAFT_ISSUE and
+            // should never count as repo-issue overlap.
+            if (node.type === "ISSUE" &&
+                node.content?.__typename === "Issue" &&
+                typeof node.content.number === "number") {
+                numbers.add(node.content.number);
+            }
+        }
+        if (!proj.items.pageInfo.hasNextPage)
+            break;
+        cursor = proj.items.pageInfo.endCursor;
+        pages += 1;
+    }
+    return { totalCount, numbers };
+}
+/**
+ * Detect repo issues that are absent from the project board.
+ *
+ * Returns the orphan summary when at least one orphan exists, or `null`
+ * when the board contains every OPEN repo issue.
+ *
+ * Returns `null` (not an empty result) so the `health_check` caller can
+ * omit the field entirely on a clean board — keeping the response tight
+ * for the common no-orphans case.
+ */
+export async function detectOrphanRepoIssues(client, owner, repo, projectOwner, projectNumber) {
+    const [repoSide, boardSide] = await Promise.all([
+        fetchRepoOpenIssueNumbers(client, owner, repo),
+        fetchBoardIssueNumbers(client, projectOwner, projectNumber),
+    ]);
+    // Orphans = OPEN issues in the repo whose number is NOT in the board set.
+    // We compare against the actual numbers walked rather than just totalCount,
+    // because a board may contain issues from OTHER repos (multi-repo project)
+    // — those would inflate `boardItems` but contribute zero to the overlap.
+    const orphanNumbers = [];
+    for (const n of repoSide.numbers) {
+        if (!boardSide.numbers.has(n))
+            orphanNumbers.push(n);
+    }
+    orphanNumbers.sort((a, b) => a - b);
+    if (orphanNumbers.length === 0)
+        return null;
+    return {
+        count: orphanNumbers.length,
+        repoOpen: repoSide.totalCount,
+        boardItems: boardSide.totalCount,
+        sample: orphanNumbers.slice(0, ORPHAN_SAMPLE_LIMIT),
+        note: ORPHAN_REPO_ISSUES_NOTE,
+    };
+}
+//# sourceMappingURL=health.js.map

package/dist/lib/hygiene.js

@@ -6,12 +6,13 @@
  */
 import { TERMINAL_STATES } from "./workflow-states.js";
 import { groupDashboardItemsByRepo } from "./dashboard.js";
+import { ARCHIVE_AGE_DAYS, ORPHAN_AGE_DAYS, RECENT_WINDOW_DAYS, SIMILARITY_THRESHOLD, } from "./thresholds.js";
 export const DEFAULT_HYGIENE_CONFIG = {
-    archiveDays: 14,
-    staleDays: 7,
-    orphanDays: 14,
+    archiveAgeDays: ARCHIVE_AGE_DAYS,
+    staleDays: RECENT_WINDOW_DAYS,
+    orphanDays: ORPHAN_AGE_DAYS,
     wipLimits: {},
-    similarityThreshold: 0.8,
+    similarityThreshold: SIMILARITY_THRESHOLD,
 };
 // ---------------------------------------------------------------------------
 // Helpers
@@ -32,9 +33,9 @@ function toHygieneItem(item, now) {
 // Section functions
 // ---------------------------------------------------------------------------
 /**
- * Items in terminal states (Done/Canceled) older than archiveDays.
+ * Items in terminal states (Done/Canceled) older than archiveAgeDays.
  */
-export function findArchiveCandidates(items, now, archiveDays) {
+export function findArchiveCandidates(items, now, archiveAgeDays) {
     return items
         .filter((item) => {
         if (item.subIssueCount > 0)
@@ -43,7 +44,7 @@ export function findArchiveCandidates(items, now, archiveDays) {
         if (!ws || !TERMINAL_STATES.includes(ws))
             return false;
         const ts = item.closedAt ?? item.updatedAt;
-        return ageDays(ts, now) > archiveDays;
+        return ageDays(ts, now) > archiveAgeDays;
     })
         .map((item) => toHygieneItem(item, now));
 }
@@ -199,7 +200,7 @@ export function findDuplicateCandidates(items, now, threshold) {
  * Does NOT recursively emit `repoBreakdowns` — per-repo breakdowns are flat.
  */
 function buildRepoBreakdown(repoName, items, config, now) {
-    const archiveCandidates = findArchiveCandidates(items, now, config.archiveDays);
+    const archiveCandidates = findArchiveCandidates(items, now, config.archiveAgeDays);
     const staleItems = findStaleItems(items, now, config.staleDays);
     const orphanedItems = findOrphanedItems(items, now, config.orphanDays);
     const fieldGaps = findFieldGaps(items, now);
@@ -235,7 +236,7 @@ function buildRepoBreakdown(repoName, items, config, now) {
  * Build a complete hygiene report from project items.
  */
 export function buildHygieneReport(items, config = DEFAULT_HYGIENE_CONFIG, now = Date.now()) {
-    const archiveCandidates = findArchiveCandidates(items, now, config.archiveDays);
+    const archiveCandidates = findArchiveCandidates(items, now, config.archiveAgeDays);
     const staleItems = findStaleItems(items, now, config.staleDays);
     const orphanedItems = findOrphanedItems(items, now, config.orphanDays);
     const fieldGaps = findFieldGaps(items, now);

package/dist/lib/metrics.js

@@ -4,10 +4,11 @@
  * All functions are side-effect-free: dashboard data in, metrics out.
  * Designed to complement lib/dashboard.ts without modifying it.
  */
+import { AT_RISK_THRESHOLD, OFF_TRACK_THRESHOLD, RECENT_WINDOW_DAYS, } from "./thresholds.js";
 export const DEFAULT_METRICS_CONFIG = {
-    velocityWindowDays: 7,
-    atRiskThreshold: 2,
-    offTrackThreshold: 6,
+    velocityWindowDays: RECENT_WINDOW_DAYS,
+    atRiskThreshold: AT_RISK_THRESHOLD,
+    offTrackThreshold: OFF_TRACK_THRESHOLD,
     severityWeights: { critical: 3, warning: 1, info: 0 },
 };
 // ---------------------------------------------------------------------------

package/dist/lib/thresholds.js

@@ -0,0 +1,44 @@
+/**
+ * Shared threshold defaults across discovery tools.
+ *
+ * Single source of truth for every "magic number" that gates the
+ * discovery surface (next_actions, pipeline_dashboard, project_hygiene,
+ * metrics_trends). Per-module CONFIG objects (DEFAULT_RANK_CONFIG,
+ * DEFAULT_HEALTH_CONFIG, DEFAULT_HYGIENE_CONFIG, DEFAULT_METRICS_CONFIG)
+ * pull from this module so changing a value in one place propagates
+ * everywhere it's referenced.
+ *
+ * Where the same value appears under multiple names (RECENT_WINDOW_DAYS),
+ * the names describe distinct concepts but the value is shared so changing
+ * one changes all related places.
+ */
+// Lock-state staleness — short, hours-based because lock collisions are urgent.
+export const LOCK_STALE_HOURS = 24;
+// PR staleness — short, hours-based because review timeliness matters.
+export const PR_STALE_HOURS = 24;
+// Non-lock stuck threshold — longer, hours-based for warnings.
+export const STUCK_THRESHOLD_HOURS = 48;
+export const CRITICAL_STUCK_HOURS = STUCK_THRESHOLD_HOURS * 2;
+// Recent activity window — single shared value for "recent enough to be relevant."
+// Used by:
+//   - hygiene.staleDays              → "non-terminal item hasn't moved in N days"
+//   - dashboard.doneWindowDays       → "show recent completions"
+//   - directions.treeRecentDoneDays  → "sibling done within window"
+//   - metrics.velocityWindowDays     → "completion window for velocity calc"
+export const RECENT_WINDOW_DAYS = 7;
+// Archive age — unified replacement for the old archiveThresholdDays
+// (dashboard) + archiveDays (hygiene) duplication. Both previously
+// defaulted to 14 and described the same concept (Done/Canceled item age
+// before archive eligibility).
+export const ARCHIVE_AGE_DAYS = 14;
+// Backlog assignment-gap — separate concept from archive age.
+export const ORPHAN_AGE_DAYS = 14;
+// Risk score classifications.
+export const AT_RISK_THRESHOLD = 2;
+export const OFF_TRACK_THRESHOLD = 6;
+// Duplicate detection similarity (0-1).
+export const SIMILARITY_THRESHOLD = 0.8;
+// Phase 1 fallback penalty — keeps Backlog items below actionable items
+// when the audience="agent" fallback fires.
+export const AGENT_BACKLOG_FALLBACK_PENALTY = 100;
+//# sourceMappingURL=thresholds.js.map

package/dist/tools/dashboard-tools.js

@@ -43,7 +43,7 @@ export function registerDashboardTools(server, client, fieldCache) {
             .number()
             .optional()
             .default(48)
-            .describe("Hours before flagging stuck issues (default: 48)"),
+            .describe("Hours before flagging stuck issues (default: 48, unit: hours). Shared with next_actions.stuckThresholdHours — both pull from STUCK_THRESHOLD_HOURS in src/lib/thresholds.ts."),
         wipLimits: z
             .record(z.coerce.number())
             .optional()
@@ -52,7 +52,7 @@ export function registerDashboardTools(server, client, fieldCache) {
             .number()
             .optional()
             .default(7)
-            .describe("Only show Done issues from last N days (default: 7)"),
+            .describe("Only show Done issues from last N days (default: 7, unit: days). Shares the RECENT_WINDOW_DAYS value with hygiene.staleDays, next_actions.treeRecentDoneDays, and metrics.velocityWindowDays."),
         issuesPerPhase: z
             .number()
             .optional()
@@ -67,22 +67,22 @@ export function registerDashboardTools(server, client, fieldCache) {
             .number()
             .optional()
             .default(7)
-            .describe("Days to look back for velocity calculation (default: 7)"),
+            .describe("Days to look back for velocity calculation (default: 7, unit: days). Shares the RECENT_WINDOW_DAYS value with hygiene.staleDays, dashboard.doneWindowDays, and next_actions.treeRecentDoneDays."),
         atRiskThreshold: z
             .number()
             .optional()
             .default(2)
-            .describe("Risk score threshold for AT_RISK status (default: 2)"),
+            .describe("Risk score threshold for AT_RISK status (default: 2, unit: count). Pulls from AT_RISK_THRESHOLD in src/lib/thresholds.ts."),
         offTrackThreshold: z
             .number()
             .optional()
             .default(6)
-            .describe("Risk score threshold for OFF_TRACK status (default: 6)"),
-        archiveThresholdDays: z
+            .describe("Risk score threshold for OFF_TRACK status (default: 6, unit: count). Pulls from OFF_TRACK_THRESHOLD in src/lib/thresholds.ts."),
+        archiveAgeDays: z
             .number()
             .optional()
             .default(14)
-            .describe("Days in Done/Canceled before eligible for archive (default: 14)"),
+            .describe("Days in Done/Canceled before eligible for archive (default: 14, unit: days). Same concept as project_hygiene.archiveAgeDays — both renamed from the legacy archiveThresholdDays/archiveDays pair so the value is shared across discovery tools."),
         streams: z
             .array(z.object({
             id: z.string(),
@@ -134,7 +134,7 @@ export function registerDashboardTools(server, client, fieldCache) {
                 criticalStuckHours: (args.stuckThresholdHours ?? 48) * 2,
                 wipLimits: args.wipLimits ?? {},
                 doneWindowDays: args.doneWindowDays ?? 7,
-                archiveThresholdDays: args.archiveThresholdDays ?? 14,
+                archiveAgeDays: args.archiveAgeDays ?? 14,
             };
             // Build dashboard from merged items
             const dashboard = buildDashboard(allItems, healthConfig, undefined, args.streams);

package/dist/tools/directions-tools.js

@@ -334,25 +334,25 @@ export function registerDirectionsTools(server, client, fieldCache) {
             .nonnegative()
             .optional()
             .default(48)
-            .describe("Hours before a non-lock issue is considered stale (default: 48)."),
+            .describe("Hours before a non-lock issue is considered stale (default: 48, unit: hours). Pulls from STUCK_THRESHOLD_HOURS in src/lib/thresholds.ts."),
         lockStaleHours: z
             .number()
             .nonnegative()
             .optional()
             .default(24)
-            .describe("Hours before a lock-state issue is considered stalled (default: 24)."),
+            .describe("Hours before a lock-state issue is considered stalled (default: 24, unit: hours). Pulls from LOCK_STALE_HOURS in src/lib/thresholds.ts."),
         treeRecentDoneDays: z
             .number()
             .nonnegative()
             .optional()
             .default(7)
-            .describe("Days within which a sibling Done event still pulls a tree forward (default: 7)."),
+            .describe("Days within which a sibling Done event still pulls a tree forward (default: 7, unit: days). Pulls from RECENT_WINDOW_DAYS in src/lib/thresholds.ts."),
         prStaleHours: z
             .number()
             .nonnegative()
             .optional()
             .default(24)
-            .describe("Hours before an open PR is considered stale (default: 24)."),
+            .describe("Hours before an open PR is considered stale (default: 24, unit: hours). Pulls from PR_STALE_HOURS in src/lib/thresholds.ts."),
     }, async (args) => {
         return await runDirections({ ...args, audience: "human" });
     });
@@ -382,25 +382,25 @@ export function registerDirectionsTools(server, client, fieldCache) {
             .nonnegative()
             .optional()
             .default(48)
-            .describe("Hours before a non-lock issue is considered stale (default: 48)."),
+            .describe("Hours before a non-lock issue is considered stale (default: 48, unit: hours). Shared with pipeline_dashboard.stuckThresholdHours — both pull from STUCK_THRESHOLD_HOURS in src/lib/thresholds.ts."),
         lockStaleHours: z
             .number()
             .nonnegative()
             .optional()
             .default(24)
-            .describe("Hours before a lock-state issue is considered stalled (default: 24)."),
+            .describe("Hours before a lock-state issue is considered stalled (default: 24, unit: hours). Pulls from LOCK_STALE_HOURS in src/lib/thresholds.ts."),
         treeRecentDoneDays: z
             .number()
             .nonnegative()
             .optional()
             .default(7)
-            .describe("Days within which a sibling Done event still pulls a tree forward (default: 7)."),
+            .describe("Days within which a sibling Done event still pulls a tree forward (default: 7, unit: days). Shares the RECENT_WINDOW_DAYS value with hygiene.staleDays, dashboard.doneWindowDays, and metrics.velocityWindowDays."),
         prStaleHours: z
             .number()
             .nonnegative()
             .optional()
             .default(24)
-            .describe("Hours before an open PR is considered stale (default: 24)."),
+            .describe("Hours before an open PR is considered stale (default: 24, unit: hours). Pulls from PR_STALE_HOURS in src/lib/thresholds.ts."),
     }, async (args) => {
         return await runDirections({ ...args, audience: args.audience ?? "human" });
     });

package/dist/tools/hygiene-tools.js

@@ -23,21 +23,21 @@ export function registerHygieneTools(server, client, fieldCache) {
             .array(z.coerce.number())
             .optional()
             .describe("Project numbers to include. Defaults to RALPH_GH_PROJECT_NUMBERS or single configured project."),
-        archiveDays: z
+        archiveAgeDays: z
             .number()
             .optional()
             .default(14)
-            .describe("Days before Done/Canceled items become archive candidates (default: 14)"),
+            .describe("Days before Done/Canceled items become archive candidates (default: 14, unit: days). Same concept as pipeline_dashboard.archiveAgeDays — both renamed from the legacy archiveDays/archiveThresholdDays pair so the value is shared across discovery tools."),
         staleDays: z
             .number()
             .optional()
             .default(7)
-            .describe("Days before non-terminal items are flagged as stale (default: 7)"),
+            .describe("Days before non-terminal items are flagged as stale (default: 7, unit: days). Shares the RECENT_WINDOW_DAYS value with dashboard.doneWindowDays, next_actions.treeRecentDoneDays, and metrics.velocityWindowDays."),
         orphanDays: z
             .number()
             .optional()
             .default(14)
-            .describe("Days before unassigned Backlog items are flagged as orphaned (default: 14)"),
+            .describe("Days before unassigned Backlog items are flagged as orphaned (default: 14, unit: days). Pulls from ORPHAN_AGE_DAYS in src/lib/thresholds.ts (separate concept from archiveAgeDays)."),
         wipLimits: z
             .record(z.coerce.number())
             .optional()
@@ -46,7 +46,7 @@ export function registerHygieneTools(server, client, fieldCache) {
             .number()
             .optional()
             .default(0.8)
-            .describe("Similarity threshold for duplicate detection (0.5-1.0, default: 0.8)"),
+            .describe("Similarity threshold for duplicate detection (0.5-1.0, default: 0.8, unit: ratio). Pulls from SIMILARITY_THRESHOLD in src/lib/thresholds.ts."),
         format: z
             .enum(["json", "markdown"])
             .optional()
@@ -89,7 +89,7 @@ export function registerHygieneTools(server, client, fieldCache) {
             // Build hygiene config
             const hygieneConfig = {
                 ...DEFAULT_HYGIENE_CONFIG,
-                archiveDays: args.archiveDays ?? 14,
+                archiveAgeDays: args.archiveAgeDays ?? 14,
                 staleDays: args.staleDays ?? 7,
                 orphanDays: args.orphanDays ?? 14,
                 wipLimits: args.wipLimits ?? {},

package/dist/tools/trends-tools.js

@@ -29,7 +29,7 @@ export function registerTrendsTools(server, client, fieldCache) {
             .int()
             .positive()
             .default(7)
-            .describe("Velocity / highlights window in days (default: 7)."),
+            .describe("Velocity / highlights window in days (default: 7, unit: days). Shares the RECENT_WINDOW_DAYS value with hygiene.staleDays, dashboard.doneWindowDays, next_actions.treeRecentDoneDays, and metrics.velocityWindowDays."),
     }, async (args) => {
         try {
             const owner = resolveProjectOwner(client.config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-mcp-server",
-  "version": "2.5.118",
+  "version": "2.5.120",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",