fix(#2559): remove stale year injection from research agent web search instructions

LLMs interpreted "Always include current year" as appending their training
cutoff year (e.g. 2024), returning stale results. Replace with explicit
prohibition and recommend --freshness or "latest"/"current" qualifiers.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

agents/gsd-phase-researcher.md

@@ -145,7 +145,7 @@ When researching "best library for X": find what the ecosystem actually uses, do
 1. `mcp__context7__resolve-library-id` with libraryName
 2. `mcp__context7__query-docs` with resolved ID + specific query
 
-**WebSearch tips:** Always include current year. Use multiple query variations. Cross-verify with authoritative sources.
+**WebSearch tips:** Do NOT append a specific year to queries — search engines already rank by recency, and a hardcoded year returns stale results once that year passes. Use `--freshness week` or `--freshness month` for recency, or add "latest" / "current" as a qualifier. Use multiple query variations. Cross-verify with authoritative sources.
 
 ## Enhanced Web Search (Brave API)
 

agents/gsd-project-researcher.md

@@ -116,12 +116,12 @@ For finding what exists, community patterns, real-world usage.
 
 **Query templates:**
 ```
-Ecosystem: "[tech] best practices [current year]", "[tech] recommended libraries [current year]"
+Ecosystem: "[tech] best practices latest", "[tech] recommended libraries current"
 Patterns:  "how to build [type] with [tech]", "[tech] architecture patterns"
 Problems:  "[tech] common mistakes", "[tech] gotchas"
 ```
 
-Always include current year. Use multiple query variations. Mark WebSearch-only findings as LOW confidence.
+Do NOT append a specific year to queries — hardcoded years return stale results once that year passes. Use "latest" / "current" as qualifiers, or use `--freshness week|month` for recency. Use multiple query variations. Mark WebSearch-only findings as LOW confidence.
 
 ### Enhanced Web Search (Brave API)
 

tests/bug-2559-stale-search-year.test.cjs

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * Bug #2559: Research phase appends hardcoded year to web search queries.
+ *
+ * Both gsd-phase-researcher and gsd-project-researcher instructed agents to
+ * "Always include current year" in web searches. LLMs interpret this as adding
+ * their training cutoff year (e.g., "2024"), returning stale results.
+ *
+ * Fix: Remove year-append instruction; use "latest"/"current" or --freshness.
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PHASE_RESEARCHER = path.join(__dirname, '..', 'agents', 'gsd-phase-researcher.md');
+const PROJECT_RESEARCHER = path.join(__dirname, '..', 'agents', 'gsd-project-researcher.md');
+
+describe('research phase web search — no stale year injection (#2559)', () => {
+  test('gsd-phase-researcher.md must not instruct "Always include current year"', () => {
+    const src = fs.readFileSync(PHASE_RESEARCHER, 'utf-8');
+    assert.ok(
+      !src.includes('Always include current year'),
+      'gsd-phase-researcher must not instruct agents to append "current year" to searches',
+    );
+  });
+
+  test('gsd-project-researcher.md must not instruct "Always include current year"', () => {
+    const src = fs.readFileSync(PROJECT_RESEARCHER, 'utf-8');
+    assert.ok(
+      !src.includes('Always include current year'),
+      'gsd-project-researcher must not instruct agents to append "current year" to searches',
+    );
+  });
+
+  test('gsd-phase-researcher.md must instruct against hardcoded year in queries', () => {
+    const src = fs.readFileSync(PHASE_RESEARCHER, 'utf-8');
+    assert.ok(
+      src.includes('hardcoded year') || src.includes('specific year') || src.includes('Do NOT append'),
+      'gsd-phase-researcher must warn against hardcoded year in search queries',
+    );
+  });
+
+  test('gsd-project-researcher.md must instruct against hardcoded year in queries', () => {
+    const src = fs.readFileSync(PROJECT_RESEARCHER, 'utf-8');
+    assert.ok(
+      src.includes('hardcoded year') || src.includes('specific year') || src.includes('Do NOT append'),
+      'gsd-project-researcher must warn against hardcoded year in search queries',
+    );
+  });
+
+  test('gsd-project-researcher.md query templates must use "latest"/"current" not "[current year]"', () => {
+    const src = fs.readFileSync(PROJECT_RESEARCHER, 'utf-8');
+    assert.ok(
+      !src.includes('[current year]'),
+      'gsd-project-researcher query templates must not contain "[current year]" placeholder',
+    );
+  });
+});