ralph-hero-mcp-server 2.5.117 → 2.5.119

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) {
@@ -512,7 +513,7 @@ export function buildDashboard(items, config = DEFAULT_HEALTH_CONFIG, now = Date
     const iterationSection = buildIterationSection(items);
     return {
         generatedAt: new Date(now).toISOString(),
-        totalIssues: items.length,
+        boardItems: items.length,
         phases,
         health: {
             ok: warnings.length === 0,
@@ -536,7 +537,7 @@ export function formatMarkdown(data, issuesPerPhase = 10) {
     lines.push(`# Pipeline Status`);
     lines.push(`_Generated: ${data.generatedAt}_`);
     lines.push("");
-    lines.push(`**Total issues**: ${data.totalIssues}`);
+    lines.push(`**Board items**: ${data.boardItems}`);
     lines.push("");
     // Phase table
     lines.push("| Phase | Count | Points | Issues |");
@@ -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/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);
@@ -262,7 +263,7 @@ export function buildHygieneReport(items, config = DEFAULT_HYGIENE_CONFIG, now =
     }
     return {
         generatedAt: new Date(now).toISOString(),
-        totalItems: items.length,
+        boardItems: items.length,
         archiveCandidates,
         staleItems,
         orphanedItems,
@@ -294,7 +295,7 @@ export function formatHygieneMarkdown(report) {
     lines.push("# Project Hygiene Report");
     lines.push(`_Generated: ${report.generatedAt}_`);
     lines.push("");
-    lines.push(`**Total items**: ${report.totalItems}`);
+    lines.push(`**Board items**: ${report.boardItems}`);
     lines.push("");
     // Summary
     lines.push("## Summary");

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

@@ -20,7 +20,7 @@ export { DASHBOARD_ITEMS_QUERY, toDashboardItems };
 // Register dashboard tools
 // ---------------------------------------------------------------------------
 export function registerDashboardTools(server, client, fieldCache) {
-    server.tool("ralph_hero__pipeline_dashboard", "Generate pipeline status dashboard with issue counts per workflow phase, health indicators, and formatted output. Returns structured data with optional markdown or ASCII rendering.", {
+    server.tool("ralph_hero__pipeline_dashboard", "Generate pipeline status dashboard with issue counts per workflow phase, health indicators, and formatted output. Returns structured data with optional markdown or ASCII rendering. Top-level `boardItems` is the raw count of all project items including PRs (uniform across discovery tools — next_actions, pipeline_dashboard, project_hygiene). Per-phase `count` values reflect that phase's bucket; for `Done` and `Canceled`, the count is bounded by `doneWindowDays` (default 7) and may be smaller than the actual phase membership. Per-iteration `totalIssues` is a distinct concept (iteration-scoped count).", {
         owner: z
             .string()
             .optional()
@@ -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

@@ -20,7 +20,7 @@
  *   5. Build a `RankConfig` from the args + defaults (with injected `now`).
  *   6. Compute each PR's `ageHours` at the boundary and call
  *      `rankDirections(allItems, enrichedPRs, config)`.
- *   7. Return `{ directions, fetchedAt, totalCandidates }`.
+ *   7. Return `{ directions, fetchedAt, boardItems }`.
  *
  * Determinism: `fetchedAt` is the only time-varying field. Two consecutive
  * calls on the same board state produce byte-identical `directions[]`
@@ -295,7 +295,11 @@ export function makeRunDirections(client, fieldCache) {
             return toolSuccess({
                 directions,
                 fetchedAt: now.toISOString(),
-                totalCandidates: allItems.length,
+                // `boardItems` is the raw count of items on the project board pre-filter
+                // (sum across all configured project numbers). Uniform across discovery
+                // tools (next_actions, pipeline_dashboard, project_hygiene). The number
+                // of returned `directions` is bounded by `limit` and may be much smaller.
+                boardItems: allItems.length,
             });
         }
         catch (error) {
@@ -309,7 +313,7 @@ export function makeRunDirections(client, fieldCache) {
 // ---------------------------------------------------------------------------
 export function registerDirectionsTools(server, client, fieldCache) {
     const runDirections = makeRunDirections(client, fieldCache);
-    server.tool("ralph_hero__hello_directions", "[DEPRECATED — use ralph_hero__next_actions instead. Removed in 2.7.0.] Compute up to N deterministic 'directions' for the hello skill's session briefing. Open PRs are fetched internally via the configured GitHub token's `repo` scope (one `is:pr is:open repo:owner/name` GraphQL search per unique repo represented in the project items). Each direction includes a structured signals object (staleDays, staleThresholdDays, tiedAtScore, estimateWeight, parentChainNote) for skills to synthesize prose. The legacy 'reason' string is @deprecated and removed in 2.7.0.", {
+    server.tool("ralph_hero__hello_directions", "[DEPRECATED — use ralph_hero__next_actions instead. Removed in 2.7.0.] Compute up to N deterministic 'directions' for the hello skill's session briefing. Open PRs are fetched internally via the configured GitHub token's `repo` scope (one `is:pr is:open repo:owner/name` GraphQL search per unique repo represented in the project items). Each direction includes a structured signals object (staleDays, staleThresholdDays, tiedAtScore, estimateWeight, parentChainNote) for skills to synthesize prose. The legacy 'reason' string is @deprecated and removed in 2.7.0. Returns `{ directions, fetchedAt, boardItems }` where `boardItems` is the raw count of items on the project board pre-filter (uniform across discovery tools); the returned `directions` array is bounded by `limit`.", {
         owner: z
             .string()
             .optional()
@@ -330,29 +334,29 @@ 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" });
     });
-    server.tool("ralph_hero__next_actions", "Compute up to N deterministic 'directions' (next actions) with one flagged `recommended: true`. Used by the /hello skill picker (interactive) and by headless orchestrators (auto-select recommended). Open PRs are fetched internally via the configured GitHub token's `repo` scope (one `is:pr is:open repo:owner/name` GraphQL search per unique repo represented in the project items) — callers no longer pass an `openPRs` argument. Each direction includes a structured signals object (staleDays, staleThresholdDays, tiedAtScore, estimateWeight, parentChainNote) for skills to synthesize prose. The legacy 'reason' string is @deprecated and removed in 2.7.0. When `audience='agent'` and no items are in actionable phases (Plan in Review, In Review, Ready for Plan, Research Needed) or otherwise surfacing (lock-stale, unblock-requested), the picker falls back to Backlog and null-state items so autopilot can drive triage. Fallback items receive a fixed score penalty so they never outrank actionable items when those exist; the fallback never fires for `audience='human'`.", {
+    server.tool("ralph_hero__next_actions", "Compute up to N deterministic 'directions' (next actions) with one flagged `recommended: true`. Used by the /hello skill picker (interactive) and by headless orchestrators (auto-select recommended). Open PRs are fetched internally via the configured GitHub token's `repo` scope (one `is:pr is:open repo:owner/name` GraphQL search per unique repo represented in the project items) — callers no longer pass an `openPRs` argument. Each direction includes a structured signals object (staleDays, staleThresholdDays, tiedAtScore, estimateWeight, parentChainNote) for skills to synthesize prose. The legacy 'reason' string is @deprecated and removed in 2.7.0. When `audience='agent'` and no items are in actionable phases (Plan in Review, In Review, Ready for Plan, Research Needed) or otherwise surfacing (lock-stale, unblock-requested), the picker falls back to Backlog and null-state items so autopilot can drive triage. Fallback items receive a fixed score penalty so they never outrank actionable items when those exist; the fallback never fires for `audience='human'`. Returns `{ directions, fetchedAt, boardItems }` where `boardItems` is the raw count of items on the project board pre-filter (uniform across discovery tools); the returned `directions` array is bounded by `limit`.", {
         owner: z
             .string()
             .optional()
@@ -378,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

@@ -14,7 +14,7 @@ import { toolSuccess, toolError, resolveProjectOwner, resolveProjectNumbers, } f
 // Register hygiene tools
 // ---------------------------------------------------------------------------
 export function registerHygieneTools(server, client, fieldCache) {
-    server.tool("ralph_hero__project_hygiene", "Generate a project board hygiene report. Identifies archive candidates, stale items, orphaned backlog entries, missing fields, WIP violations, and duplicate candidates. Returns: report with 7 sections + summary stats.", {
+    server.tool("ralph_hero__project_hygiene", "Generate a project board hygiene report. Identifies archive candidates, stale items, orphaned backlog entries, missing fields, WIP violations, and duplicate candidates. Returns: report with 7 sections + summary stats. Top-level `boardItems` is the raw count of items on the project board pre-filter (uniform across discovery tools — next_actions, pipeline_dashboard, project_hygiene). Per-category counts in `summary` (archiveCandidateCount, staleCount, orphanCount, fieldCoveragePercent, wipViolationCount, duplicateCandidateCount) are post-filter and represent distinct buckets.", {
         owner: z
             .string()
             .optional()
@@ -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.117",
+  "version": "2.5.119",
   "description": "MCP server for GitHub Projects V2 - Ralph workflow automation",
   "type": "module",
   "main": "dist/index.js",