euparliamentmonitor 0.8.30 → 0.8.31

package/README.md

@@ -124,7 +124,7 @@ import {
 
 **MCP Server Integration**: The project uses the
 [European-Parliament-MCP-Server](https://github.com/Hack23/European-Parliament-MCP-Server)
-v1.2.6 for accessing real EU Parliament data via the Model Context Protocol.
+v1.2.7 for accessing real EU Parliament data via the Model Context Protocol.
 
 - **MCP Server Status**: ✅ Fully operational — 60+ EP data tools available
   (feeds, direct lookups, analytical tools, intelligence correlation)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euparliamentmonitor",
-  "version": "0.8.30",
+  "version": "0.8.31",
   "type": "module",
   "description": "European Parliament Intelligence Platform - Monitor political activity with systematic transparency",
   "main": "scripts/index.js",
@@ -159,7 +159,7 @@
     "jscpd": "4.0.9",
     "lint-staged": "16.4.0",
     "papaparse": "5.5.3",
-    "prettier": "3.8.2",
+    "prettier": "3.8.3",
     "ts-api-utils": "2.5.0",
     "tsx": "4.21.0",
     "typedoc": "0.28.19",
@@ -170,7 +170,7 @@
     "node": ">=25"
   },
   "dependencies": {
-    "european-parliament-mcp-server": "1.2.6"
+    "european-parliament-mcp-server": "1.2.7"
   },
   "optionalDependencies": {
     "worldbank-mcp": "1.0.1"

package/scripts/generators/motions-content.js

@@ -349,9 +349,13 @@ export function buildAdoptedTextsSection(adoptedTexts, language) {
     if (adoptedTexts.length === 0)
         return '';
     const heading = ADOPTED_TEXTS_HEADINGS[language] ?? ADOPTED_TEXTS_HEADINGS['en'] ?? 'Recently Adopted Texts';
-    const countFn = ADOPTED_TEXTS_COUNT_STRINGS[language] ?? ADOPTED_TEXTS_COUNT_STRINGS['en'];
+    const countFn = ADOPTED_TEXTS_COUNT_STRINGS[language] ??
+        ADOPTED_TEXTS_COUNT_STRINGS['en'] ??
+        ((n) => `${n} adopted texts`);
     const countText = countFn(adoptedTexts.length);
-    const unknownDate = ADOPTED_TEXTS_DATE_UNKNOWN_STRINGS[language] ?? ADOPTED_TEXTS_DATE_UNKNOWN_STRINGS['en'];
+    const unknownDate = ADOPTED_TEXTS_DATE_UNKNOWN_STRINGS[language] ??
+        ADOPTED_TEXTS_DATE_UNKNOWN_STRINGS['en'] ??
+        'Unknown date';
     // Group by date, sort most recent first
     const byDate = new Map();
     for (const item of adoptedTexts) {

package/scripts/generators/news-enhanced.js

@@ -118,8 +118,9 @@ let languagesInput = languagesArg
     ? (languagesArg.split(ARG_SEPARATOR)[1] ?? '').trim().toLowerCase()
     : 'en';
 // Expand presets
-if (LANGUAGE_PRESETS[languagesInput]) {
-    languagesInput = LANGUAGE_PRESETS[languagesInput].join(',');
+const presetLanguages = LANGUAGE_PRESETS[languagesInput];
+if (presetLanguages) {
+    languagesInput = presetLanguages.join(',');
 }
 const languages = languagesInput
     .split(',')
@@ -402,7 +403,7 @@ function wireAIMetadata() {
  */
 export function computeDedupSuffix(articleTypes, analysisDir) {
     const baseSlugNoRun = deriveArticleTypeSlug(articleTypes.filter((t) => VALID_ARTICLE_CATEGORIES.includes(t)));
-    const rawSuffix = analysisDir !== undefined && analysisDir.startsWith(baseSlugNoRun)
+    const rawSuffix = analysisDir?.startsWith(baseSlugNoRun)
         ? analysisDir.slice(baseSlugNoRun.length)
         : '';
     // Suffix validation patterns for dedup suffix extraction.

package/scripts/generators/pipeline/fetch-stage.js

@@ -427,16 +427,16 @@ export async function fetchWeekAheadData(client, dateRange) {
     const wasHalfOpen = mcpCircuitBreaker.getState() === 'HALF_OPEN';
     console.log(`${MCP_FETCH_PREFIX} Fetching week-ahead data from MCP (parallel)...`);
     const [plenarySessions, committeeInfo, documents, pipeline, questions, epEvents] = await Promise.allSettled([
-        client.getPlenarySessions({ startDate: dateRange.start, endDate: dateRange.end, limit: 50 }),
-        client.getCommitteeInfo({ limit: 20 }),
-        client.searchDocuments({ query: 'parliament', limit: 20 }),
+        client.getPlenarySessions({ dateFrom: dateRange.start, dateTo: dateRange.end, limit: 50 }),
+        client.getCommitteeInfo({ showCurrent: true }),
+        client.searchDocuments({ keyword: 'parliament', limit: 20 }),
         client.monitorLegislativePipeline({
             dateFrom: dateRange.start,
             dateTo: dateRange.end,
             status: 'ACTIVE',
             limit: 20,
         }),
-        client.getParliamentaryQuestions({ startDate: dateRange.start, limit: 20 }),
+        client.getParliamentaryQuestions({ dateFrom: dateRange.start, limit: 20 }),
         client.getEvents({ dateFrom: dateRange.start, dateTo: dateRange.end, limit: 20 }),
     ]);
     const allFailed = [
@@ -459,7 +459,7 @@ export async function fetchWeekAheadData(client, dateRange) {
     const additionalEvents = parseEPEvents(epEvents, dateRange.start);
     const events = [...plenaryEvents, ...additionalEvents];
     return {
-        events: events.length > 0 ? events : [{ ...PLACEHOLDER_EVENTS[0], date: dateRange.start }],
+        events: events.length > 0 ? events : PLACEHOLDER_EVENTS.map((e) => ({ ...e, date: dateRange.start })),
         committees: parseCommitteeMeetings(committeeInfo, dateRange.start),
         documents: parseLegislativeDocuments(documents),
         pipeline: parseLegislativePipeline(pipeline),
@@ -728,7 +728,7 @@ export async function fetchCommitteeData(client, abbreviation) {
         return defaultResult;
     try {
         console.log(`${MCP_FETCH_PREFIX} Fetching committee info for ${abbreviation}...`);
-        const committeeResult = await callMCP(() => client.getCommitteeInfo({ committeeId: abbreviation }), null, `getCommitteeInfo(${abbreviation})`);
+        const committeeResult = await callMCP(() => client.getCommitteeInfo({ abbreviation }), null, `getCommitteeInfo(${abbreviation})`);
         if (committeeResult)
             applyCommitteeInfo(committeeResult, defaultResult, abbreviation);
     }
@@ -738,7 +738,7 @@ export async function fetchCommitteeData(client, abbreviation) {
     }
     try {
         console.log(`${MCP_FETCH_PREFIX} Fetching documents for ${abbreviation}...`);
-        const docsResult = await callMCP(() => client.searchDocuments({ query: abbreviation, limit: 5 }), null, `searchDocuments(${abbreviation})`);
+        const docsResult = await callMCP(() => client.searchDocuments({ keyword: abbreviation, limit: 5 }), null, `searchDocuments(${abbreviation})`);
         if (docsResult)
             applyDocuments(docsResult, defaultResult);
     }
@@ -1062,8 +1062,7 @@ const TIMEFRAME_FALLBACK_CHAIN = new Map([
     ['one-day', 'one-week'],
     ['one-week', 'one-month'],
     ['one-month', undefined],
-    ['three-months', undefined],
-    ['one-year', undefined],
+    ['custom', undefined],
 ]);
 /**
  * Get the next wider timeframe for fallback, or `undefined` if no fallback exists.

package/scripts/generators/sitemap.js

@@ -49,7 +49,7 @@ export function collectDocsHtmlFiles(dir, rootDir = PROJECT_ROOT) {
  */
 export function generateSitemap(articles, docsFiles = []) {
     const urls = [];
-    const today = new Date().toISOString().split('T')[0];
+    const today = new Date().toISOString().slice(0, 10);
     // Add home pages for each language
     for (const lang of ALL_LANGUAGES) {
         const filename = lang === 'en' ? 'index.html' : `index-${lang}.html`;
@@ -301,8 +301,8 @@ export function generateSitemapHTML(lang, articleInfos, hasDocsDir = false) {
     const skipLinkText = getLocalizedString(SKIP_LINK_TEXTS, lang);
     const dir = getTextDirection(lang);
     const year = new Date().getFullYear();
-    const sections = SITEMAP_SECTIONS[lang] ?? SITEMAP_SECTIONS['en'];
-    const docsLabels = DOCS_LABELS[lang] ?? DOCS_LABELS['en'];
+    const sections = (SITEMAP_SECTIONS[lang] ?? SITEMAP_SECTIONS['en']);
+    const docsLabels = (DOCS_LABELS[lang] ?? DOCS_LABELS['en']);
     const heroTitle = getLocalizedString(PAGE_TITLES, lang).split(' - ')[0] ?? '';
     const headerSubtitle = escapeHTML(getLocalizedString(HEADER_SUBTITLE_LABELS, lang));
     const themeToggleLabel = escapeHTML(getLocalizedString(THEME_TOGGLE_LABELS, lang));
@@ -539,7 +539,7 @@ function main() {
     // Generate sitemap HTML for each language
     let htmlGenerated = 0;
     for (const lang of ALL_LANGUAGES) {
-        const langArticles = articlesByLang.get(lang) || [];
+        const langArticles = articlesByLang.get(lang) ?? [];
         // Sort newest first
         langArticles.sort((a, b) => b.date.localeCompare(a.date));
         const html = generateSitemapHTML(lang, langArticles, hasDocsDir);

package/scripts/generators/strategies/committee-reports-strategy.js

@@ -249,7 +249,7 @@ function buildAdoptedTextsSection(feedData, lang) {
     const sections = displayOrder
         .filter((cat) => grouped[cat]?.length)
         .map((cat) => {
-        const items = grouped[cat];
+        const items = grouped[cat] ?? [];
         const listItems = items
             .map((item) => `<li class="adopted-text-item"><strong>${escapeHTML(item.title)}</strong> <span class="document-date">(${escapeHTML(item.date)})</span></li>`)
             .join('\n                ');

package/scripts/mcp/ep-mcp-client.d.ts

@@ -70,32 +70,28 @@ export declare class EuropeanParliamentMCPClient extends MCPConnection {
     /**
      * Get plenary sessions
      *
-     * @param options - Filter options. `dateFrom` is mapped to `startDate` and `dateTo` to `endDate`
-     *   per the tool schema when the canonical fields are absent.
+     * @param options - Filter options including dateFrom, dateTo, eventId, year, location
      * @returns Plenary sessions data
      */
     getPlenarySessions(options?: GetPlenarySessionsOptions): Promise<MCPToolResult>;
     /**
      * Search legislative documents
      *
-     * @param options - Search options (normalizes `query` to `keyword` if `keyword` is absent,
-     *   since the MCP tool schema requires the `keyword` parameter)
+     * @param options - Search options using v1.2.7 parameters: keyword, documentType, docId, etc.
      * @returns Search results
      */
     searchDocuments(options?: SearchDocumentsOptions): Promise<MCPToolResult>;
     /**
      * Get parliamentary questions
      *
-     * @param options - Filter options. `dateFrom` is mapped to `startDate` per the tool schema.
-     *   `dateTo` is intentionally ignored because the `get_parliamentary_questions` tool schema
-     *   only supports `startDate` as a date filter; passing `dateTo` would have no effect.
+     * @param options - Filter options including docId, type, author, topic, status, dateFrom, dateTo
      * @returns Parliamentary questions data
      */
     getParliamentaryQuestions(options?: GetParliamentaryQuestionsOptions): Promise<MCPToolResult>;
     /**
      * Get committee information
      *
-     * @param options - Filter options
+     * @param options - Filter options: id, abbreviation, showCurrent
      * @returns Committee info data
      */
     getCommitteeInfo(options?: GetCommitteeInfoOptions): Promise<MCPToolResult>;
@@ -123,21 +119,21 @@ export declare class EuropeanParliamentMCPClient extends MCPConnection {
     /**
      * Analyze coalition dynamics and cohesion
      *
-     * @param options - Options including optional political groups and date range
+     * @param options - Options including optional groupIds and date range
      * @returns Coalition cohesion and stress analysis
      */
     analyzeCoalitionDynamics(options?: AnalyzeCoalitionDynamicsOptions): Promise<MCPToolResult>;
     /**
      * Detect voting anomalies and party defections
      *
-     * @param options - Options including optional MEP id, political group, and date
+     * @param options - Options including optional MEP id, groupId, and date range
      * @returns Anomaly detection results
      */
     detectVotingAnomalies(options?: DetectVotingAnomaliesOptions): Promise<MCPToolResult>;
     /**
      * Compare political groups across dimensions
      *
-     * @param options - Options including required groups and optional metrics and date
+     * @param options - Options including required groupIds and optional dimensions and date range
      * @returns Cross-group comparative analysis
      */
     comparePoliticalGroups(options: ComparePoliticalGroupsOptions): Promise<MCPToolResult>;
@@ -151,7 +147,7 @@ export declare class EuropeanParliamentMCPClient extends MCPConnection {
     /**
      * Retrieve voting records with optional filters
      *
-     * @param options - Filter options (mepId, sessionId, limit)
+     * @param options - Filter options (sessionId, mepId, topic, dateFrom, dateTo, limit, offset)
      * @returns Voting records data
      */
     getVotingRecords(options?: VotingRecordsOptions): Promise<MCPToolResult>;
@@ -382,10 +378,10 @@ export declare class EuropeanParliamentMCPClient extends MCPConnection {
     /**
      * Cross-tool OSINT intelligence correlation engine
      *
-     * @param options - Options including optional mepId and correlation scenarios
+     * @param options - Options including required mepIds, optional groups, sensitivityLevel, includeNetworkAnalysis
      * @returns Correlated intelligence alerts and insights
      */
-    correlateIntelligence(options?: CorrelateIntelligenceOptions): Promise<MCPToolResult>;
+    correlateIntelligence(options: CorrelateIntelligenceOptions): Promise<MCPToolResult>;
     /**
      * Retrieve precomputed European Parliament activity statistics (EP6–EP10, 2004–2025).
      * Includes yearly stats, category rankings, political landscape history, and

package/scripts/mcp/ep-mcp-client.js

@@ -29,7 +29,7 @@ const SERVER_HEALTH_FALLBACK = '{"server": null, "feeds": []}';
 /**
  * Classify an error message into a diagnostic error category.
  *
- * Maps EP MCP Server v1.2.6 structured error codes and generic HTTP/network
+ * Maps EP MCP Server v1.2.7 structured error codes and generic HTTP/network
  * errors into one of six broad categories used for logging and retry decisions:
  *
  * Returned categories (priority order):
@@ -45,7 +45,7 @@ const SERVER_HEALTH_FALLBACK = '{"server": null, "feeds": []}';
  */
 function classifyToolError(message) {
     const lowerMsg = message.toLowerCase();
-    // EP MCP Server v1.2.6 structured error codes (matched case-insensitively)
+    // EP MCP Server v1.2.7 structured error codes (matched case-insensitively)
     if (lowerMsg.includes('internal_error')) {
         return 'INTERNAL_ERROR';
     }
@@ -205,78 +205,38 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
     /**
      * Get plenary sessions
      *
-     * @param options - Filter options. `dateFrom` is mapped to `startDate` and `dateTo` to `endDate`
-     *   per the tool schema when the canonical fields are absent.
+     * @param options - Filter options including dateFrom, dateTo, eventId, year, location
      * @returns Plenary sessions data
      */
     async getPlenarySessions(options = {}) {
-        return this.safeCallTool('get_plenary_sessions', () => {
-            const { dateFrom, dateTo, ...rest } = options;
-            const normalizedOptions = { ...rest };
-            if (normalizedOptions['startDate'] === undefined && dateFrom !== undefined) {
-                normalizedOptions['startDate'] = dateFrom;
-            }
-            if (normalizedOptions['endDate'] === undefined && dateTo !== undefined) {
-                normalizedOptions['endDate'] = dateTo;
-            }
-            return normalizedOptions;
-        }, '{"sessions": []}');
+        return this.safeCallTool('get_plenary_sessions', options, '{"sessions": []}');
     }
     /**
      * Search legislative documents
      *
-     * @param options - Search options (normalizes `query` to `keyword` if `keyword` is absent,
-     *   since the MCP tool schema requires the `keyword` parameter)
+     * @param options - Search options using v1.2.7 parameters: keyword, documentType, docId, etc.
      * @returns Search results
      */
     async searchDocuments(options = {}) {
-        return this.safeCallTool('search_documents', () => {
-            const { query, ...rest } = options;
-            const normalizedOptions = { ...rest };
-            // MCP tool schema expects 'keyword', not 'query'
-            if (normalizedOptions['keyword'] === undefined && query !== undefined) {
-                const trimmed = String(query).trim();
-                if (trimmed.length > 0) {
-                    normalizedOptions['keyword'] = trimmed;
-                }
-            }
-            return normalizedOptions;
-        }, DOCUMENTS_FALLBACK);
+        return this.safeCallTool('search_documents', options, DOCUMENTS_FALLBACK);
     }
     /**
      * Get parliamentary questions
      *
-     * @param options - Filter options. `dateFrom` is mapped to `startDate` per the tool schema.
-     *   `dateTo` is intentionally ignored because the `get_parliamentary_questions` tool schema
-     *   only supports `startDate` as a date filter; passing `dateTo` would have no effect.
+     * @param options - Filter options including docId, type, author, topic, status, dateFrom, dateTo
      * @returns Parliamentary questions data
      */
     async getParliamentaryQuestions(options = {}) {
-        return this.safeCallTool('get_parliamentary_questions', () => {
-            const { dateFrom, dateTo: _dateTo, ...rest } = options;
-            const toolOptions = { ...rest };
-            if (toolOptions['startDate'] === undefined && dateFrom !== undefined) {
-                toolOptions['startDate'] = dateFrom;
-            }
-            return toolOptions;
-        }, '{"questions": []}');
+        return this.safeCallTool('get_parliamentary_questions', options, '{"questions": []}');
     }
     /**
      * Get committee information
      *
-     * @param options - Filter options
+     * @param options - Filter options: id, abbreviation, showCurrent
      * @returns Committee info data
      */
     async getCommitteeInfo(options = {}) {
-        return this.safeCallTool('get_committee_info', () => {
-            const { committeeId, ...rest } = options;
-            const toolOptions = { ...rest };
-            // MCP tool schema expects 'abbreviation', not 'committeeId'
-            if (toolOptions['abbreviation'] === undefined && committeeId !== undefined) {
-                toolOptions['abbreviation'] = committeeId;
-            }
-            return toolOptions;
-        }, '{"committees": []}');
+        return this.safeCallTool('get_committee_info', options, '{"committees": []}');
     }
     /**
      * Monitor legislative pipeline
@@ -319,7 +279,7 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
     /**
      * Analyze coalition dynamics and cohesion
      *
-     * @param options - Options including optional political groups and date range
+     * @param options - Options including optional groupIds and date range
      * @returns Coalition cohesion and stress analysis
      */
     async analyzeCoalitionDynamics(options = {}) {
@@ -328,7 +288,7 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
     /**
      * Detect voting anomalies and party defections
      *
-     * @param options - Options including optional MEP id, political group, and date
+     * @param options - Options including optional MEP id, groupId, and date range
      * @returns Anomaly detection results
      */
     async detectVotingAnomalies(options = {}) {
@@ -337,19 +297,18 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
     /**
      * Compare political groups across dimensions
      *
-     * @param options - Options including required groups and optional metrics and date
+     * @param options - Options including required groupIds and optional dimensions and date range
      * @returns Cross-group comparative analysis
      */
     async comparePoliticalGroups(options) {
-        const rawGroups = options && Array.isArray(options.groups) ? options.groups : [];
-        const groups = rawGroups
+        const groupIds = (Array.isArray(options.groupIds) ? options.groupIds : [])
             .map((g) => (typeof g === 'string' ? g.trim() : ''))
             .filter((g) => g.length > 0);
-        if (groups.length === 0) {
-            console.warn('compare_political_groups called without valid groups (non-empty string array required)');
+        if (groupIds.length === 0) {
+            console.warn('compare_political_groups called without valid groupIds (non-empty string array required)');
             return { content: [{ type: 'text', text: '{"comparison": {}}' }] };
         }
-        return this.safeCallTool('compare_political_groups', { ...options, groups }, '{"comparison": {}}');
+        return this.safeCallTool('compare_political_groups', { ...options, groupIds }, '{"comparison": {}}');
     }
     /**
      * Get detailed information about a specific MEP
@@ -367,7 +326,7 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
     /**
      * Retrieve voting records with optional filters
      *
-     * @param options - Filter options (mepId, sessionId, limit)
+     * @param options - Filter options (sessionId, mepId, topic, dateFrom, dateTo, limit, offset)
      * @returns Voting records data
      */
     async getVotingRecords(options = {}) {
@@ -708,10 +667,14 @@ export class EuropeanParliamentMCPClient extends MCPConnection {
     /**
      * Cross-tool OSINT intelligence correlation engine
      *
-     * @param options - Options including optional mepId and correlation scenarios
+     * @param options - Options including required mepIds, optional groups, sensitivityLevel, includeNetworkAnalysis
      * @returns Correlated intelligence alerts and insights
      */
-    async correlateIntelligence(options = {}) {
+    async correlateIntelligence(options) {
+        if (!Array.isArray(options.mepIds) || options.mepIds.length === 0) {
+            console.warn('correlate_intelligence called without valid mepIds (non-empty string array required)');
+            return { content: [{ type: 'text', text: INTELLIGENCE_FALLBACK }] };
+        }
         return this.safeCallTool('correlate_intelligence', options, INTELLIGENCE_FALLBACK);
     }
     /**

package/scripts/mcp/mcp-connection.js

@@ -419,7 +419,7 @@ export class MCPConnection {
                 return trimmedKey;
             }
         }
-        const rawScheme = typeof process !== 'undefined' && process.env && process.env['EP_MCP_GATEWAY_AUTH_SCHEME'];
+        const rawScheme = typeof process !== 'undefined' && process.env?.['EP_MCP_GATEWAY_AUTH_SCHEME'];
         const scheme = typeof rawScheme === 'string' ? rawScheme.trim() : '';
         if (scheme && tokenRegex.test(scheme)) {
             return `${scheme} ${trimmedKey}`;
@@ -430,6 +430,9 @@ export class MCPConnection {
      * Attempt a single connection via MCP Gateway (HTTP transport)
      */
     async _attemptGatewayConnection() {
+        if (!this.gatewayUrl) {
+            throw new Error('Gateway URL not configured. Set the EP_MCP_GATEWAY_URL environment variable or provide the gatewayUrl constructor option.');
+        }
         try {
             const headers = {
                 'Content-Type': 'application/json',
@@ -562,17 +565,24 @@ export class MCPConnection {
     handleMessage(line) {
         try {
             const message = JSON.parse(line);
-            if (message.id && this.pendingRequests.has(message.id)) {
+            if (message.id !== null && message.id !== undefined && this.pendingRequests.has(message.id)) {
                 const pending = this.pendingRequests.get(message.id);
-                this.pendingRequests.delete(message.id);
-                if (message.error) {
-                    pending.reject(new Error(message.error.message ?? 'MCP server error'));
+                if (pending) {
+                    this.pendingRequests.delete(message.id);
+                    if (message.error) {
+                        pending.reject(new Error(message.error.message ?? 'MCP server error'));
+                    }
+                    else {
+                        pending.resolve(message.result);
+                    }
                 }
                 else {
-                    pending.resolve(message.result);
+                    // has() returned true but get() returned undefined — unexpected
+                    this.pendingRequests.delete(message.id);
+                    console.error(`MCP pending request ${String(message.id)} vanished before handling`);
                 }
             }
-            else if (!message.id && message.method) {
+            else if ((message.id === null || message.id === undefined) && message.method) {
                 console.log(`MCP Notification: ${message.method}`);
             }
         }
@@ -619,6 +629,9 @@ export class MCPConnection {
      * @returns Server response
      */
     async _sendGatewayRequest(method, params = {}) {
+        if (!this.gatewayUrl) {
+            throw new Error('Gateway URL not configured. Set EP_MCP_GATEWAY_URL or provide gatewayUrl in MCP client options.');
+        }
         const id = ++this.requestId;
         const request = {
             jsonrpc: '2.0',

package/scripts/types/mcp.d.ts

@@ -63,43 +63,58 @@ export interface GetMEPsOptions {
 }
 /** Options for getPlenarySessions */
 export interface GetPlenarySessionsOptions {
-    /** Tool schema field name */
-    startDate?: string | undefined;
-    /** Tool schema field name */
-    endDate?: string | undefined;
-    /** Alternative field name used by generators */
+    /** Meeting event ID for single meeting lookup */
+    eventId?: string | undefined;
+    /** Filter by calendar year (recommended for annual counts) */
+    year?: number | undefined;
+    /** Start date in YYYY-MM-DD format */
     dateFrom?: string | undefined;
-    /** Alternative field name used by generators */
+    /** End date in YYYY-MM-DD format */
     dateTo?: string | undefined;
+    /** Session location (e.g., "Strasbourg", "Brussels") */
     location?: string | undefined;
     limit?: number | undefined;
+    offset?: number | undefined;
 }
 /** Options for searchDocuments */
 export interface SearchDocumentsOptions {
-    query?: string | undefined;
+    /** Document ID for single document lookup (bypasses keyword search) */
+    docId?: string | undefined;
+    /** Search keyword or phrase */
     keyword?: string | undefined;
-    type?: string | undefined;
+    /** Document type: REPORT, RESOLUTION, DECISION, DIRECTIVE, REGULATION, OPINION, AMENDMENT */
+    documentType?: string | undefined;
     committee?: string | undefined;
     dateFrom?: string | undefined;
     dateTo?: string | undefined;
     limit?: number | undefined;
+    offset?: number | undefined;
 }
 /** Options for getParliamentaryQuestions */
 export interface GetParliamentaryQuestionsOptions {
+    /** Document ID for single question lookup */
+    docId?: string | undefined;
+    /** Question type: WRITTEN or ORAL */
     type?: string | undefined;
-    startDate?: string | undefined;
+    /** MEP identifier or name of question author */
+    author?: string | undefined;
+    /** Question topic or keyword to search */
+    topic?: string | undefined;
+    /** Question status: PENDING or ANSWERED */
+    status?: string | undefined;
     dateFrom?: string | undefined;
     dateTo?: string | undefined;
     limit?: number | undefined;
+    offset?: number | undefined;
 }
 /** Options for getCommitteeInfo */
 export interface GetCommitteeInfoOptions {
-    committeeId?: string | undefined;
-    /** Alternative field name used by callers — maps to `abbreviation` in the MCP tool schema */
+    /** Committee identifier */
+    id?: string | undefined;
+    /** Committee abbreviation (e.g., "ENVI", "AGRI") */
     abbreviation?: string | undefined;
-    dateFrom?: string | undefined;
-    dateTo?: string | undefined;
-    limit?: number | undefined;
+    /** If true, returns all current active corporate bodies */
+    showCurrent?: boolean | undefined;
 }
 /** Options for monitorLegislativePipeline */
 export interface MonitorLegislativePipelineOptions {
@@ -117,21 +132,31 @@ export interface AssessMEPInfluenceOptions {
 }
 /** Options for analyzeCoalitionDynamics */
 export interface AnalyzeCoalitionDynamicsOptions {
-    politicalGroups?: string[] | undefined;
+    /** Political group identifiers to analyze (omit for all groups) */
+    groupIds?: string[] | undefined;
     dateFrom?: string | undefined;
     dateTo?: string | undefined;
+    /** Minimum cohesion threshold for alliance detection (0-1) */
+    minimumCohesion?: number | undefined;
 }
 /** Options for detectVotingAnomalies */
 export interface DetectVotingAnomaliesOptions {
     mepId?: string | undefined;
-    politicalGroup?: string | undefined;
+    /** Political group to analyze */
+    groupId?: string | undefined;
     dateFrom?: string | undefined;
+    dateTo?: string | undefined;
+    /** Anomaly sensitivity (0-1, lower = more anomalies detected) */
+    sensitivityThreshold?: number | undefined;
 }
 /** Options for comparePoliticalGroups */
 export interface ComparePoliticalGroupsOptions {
-    groups: string[];
-    metrics?: string[] | undefined;
+    /** Political group identifiers to compare (minimum 2, maximum 10) */
+    groupIds: string[];
+    /** Comparison dimensions: voting_discipline, activity_level, legislative_output, attendance, cohesion */
+    dimensions?: string[] | undefined;
     dateFrom?: string | undefined;
+    dateTo?: string | undefined;
 }
 /** Options for analyzeLegislativeEffectiveness */
 export interface AnalyzeLegislativeEffectivenessOptions {
@@ -144,7 +169,11 @@ export interface AnalyzeLegislativeEffectivenessOptions {
 export interface VotingRecordsOptions {
     mepId?: string | undefined;
     sessionId?: string | undefined;
+    topic?: string | undefined;
+    dateFrom?: string | undefined;
+    dateTo?: string | undefined;
     limit?: number | undefined;
+    offset?: number | undefined;
 }
 /** Options for analyzing voting patterns */
 export interface VotingPatternsOptions {
@@ -192,6 +221,8 @@ export interface GetCurrentMEPsOptions {
 /** Options for getSpeeches */
 export interface GetSpeechesOptions {
     speechId?: string | undefined;
+    /** Filter by calendar year (recommended for annual counts) */
+    year?: number | undefined;
     dateFrom?: string | undefined;
     dateTo?: string | undefined;
     limit?: number | undefined;
@@ -214,6 +245,8 @@ export interface GetAdoptedTextsOptions {
 /** Options for getEvents */
 export interface GetEventsOptions {
     eventId?: string | undefined;
+    /** Filter by calendar year (recommended for annual counts) */
+    year?: number | undefined;
     dateFrom?: string | undefined;
     dateTo?: string | undefined;
     limit?: number | undefined;
@@ -338,8 +371,14 @@ export interface ComparativeIntelligenceOptions {
 }
 /** Options for correlateIntelligence */
 export interface CorrelateIntelligenceOptions {
-    mepId?: number | undefined;
-    correlationScenarios?: ('influence_anomaly' | 'coalition_stress' | 'network_activity')[] | undefined;
+    /** MEP identifiers to cross-correlate (1-5 MEPs, required) */
+    mepIds: string[];
+    /** Political groups for coalition fracture analysis (max 8, omit for all) */
+    groups?: string[] | undefined;
+    /** Alert sensitivity: HIGH, MEDIUM, or LOW */
+    sensitivityLevel?: 'HIGH' | 'MEDIUM' | 'LOW' | undefined;
+    /** Run network centrality analysis (increases response time) */
+    includeNetworkAnalysis?: boolean | undefined;
 }
 /** Allowed category values for getAllGeneratedStats */
 export type GeneratedStatsCategory = 'all' | 'plenary_sessions' | 'legislative_acts' | 'roll_call_votes' | 'committee_meetings' | 'parliamentary_questions' | 'resolutions' | 'speeches' | 'adopted_texts' | 'political_groups' | 'procedures' | 'events' | 'documents' | 'mep_turnover' | 'declarations';
@@ -356,7 +395,7 @@ export interface GetAllGeneratedStatsOptions {
  * Allowed timeframe values for EP API v2 feed endpoints.
  * Controls how far back the feed looks for recently updated items.
  */
-export type FeedTimeframe = 'today' | 'one-day' | 'one-week' | 'one-month' | 'three-months' | 'one-year';
+export type FeedTimeframe = 'today' | 'one-day' | 'one-week' | 'one-month' | 'custom';
 /** Common options shared by all EP API v2 feed endpoints */
 export interface FeedBaseOptions {
     /** How far back to look for recently-updated items (default: `'one-day'`) */

package/scripts/utils/content-validator.js

@@ -106,6 +106,89 @@ const ENGLISH_PLACEHOLDER_PHRASES = [
     'political group dynamics',
     'committee coordinators',
 ];
+// ─── Article Quality Gate Constants ───────────────────────────────────────────
+/**
+ * Section headings that MUST NOT appear as article keywords.
+ * These leak into meta tags when AI agents copy their section headers
+ * into the keywords field instead of using policy terms.
+ *
+ * @see SHARED_PROMPT_PATTERNS.md § Keywords Quality Rules
+ */
+const BANNED_KEYWORD_PATTERNS = [
+    'Deep Political Analysis',
+    'What Happened',
+    'Key Actors',
+    'Timeline',
+    'Why It Matters',
+    'Why This Matters',
+    'Legislative Pipeline Overview',
+    'Impact Assessment',
+    'Actions → Consequences',
+    'Miscalculations & Missed Opportunities',
+    'Winners & Losers',
+    'Root Causes',
+    'Stakeholder Perspectives',
+    'Multi-Stakeholder Perspectives',
+    'Stakeholder Outcome Matrix',
+    'Intelligence Policy Map',
+    'Strategic Outlook',
+    'SWOT Analysis',
+    'Dashboard',
+    'Pipeline Health',
+    'Analysis Pipeline Insights',
+    'Plenary Sessions',
+    'Executive Summary',
+    'Table of Contents',
+    'Political Context',
+];
+/**
+ * Minimum number of non-whitespace characters for a `<section>` to be
+ * considered non-empty. Below this threshold the section is treated as empty.
+ */
+const MIN_SECTION_CONTENT_LENGTH = 10;
+/**
+ * How many characters to look back from a tag position when checking
+ * whether the tag is inside a pipeline-health/pipeline-metrics container.
+ */
+const PIPELINE_CONTEXT_LOOKBEHIND_CHARS = 2000;
+/**
+ * Pre-computed normalized banned-keyword map for exact-match comparison.
+ * Built once at module init from BANNED_KEYWORD_PATTERNS + normalizeKeywordToken.
+ *
+ * Keys are normalized tokens; values are original patterns.
+ */
+let _bannedNormalizedCache;
+/**
+ * Return (and lazily compute once) the normalized banned-keyword map.
+ * Lazy initialization avoids a forward-reference to `normalizeKeywordToken`
+ * which is defined later in this module.
+ *
+ * @returns Map from normalized token to original banned pattern
+ */
+function getBannedNormalized() {
+    if (!_bannedNormalizedCache) {
+        _bannedNormalizedCache = new Map();
+        for (const pattern of BANNED_KEYWORD_PATTERNS) {
+            _bannedNormalizedCache.set(normalizeKeywordToken(pattern), pattern);
+        }
+    }
+    return _bannedNormalizedCache;
+}
+/**
+ * HTML entity → decoded character pairs used by the single-pass decoder.
+ * Longest entities are listed first so that `&amp;` doesn't greedily match
+ * inside `&amp;lt;` before the full entity `&amp;lt;` is checked.
+ */
+const ENTITY_PAIRS = [
+    ['&mdash;', '—'],
+    ['&ndash;', '–'],
+    ['&rarr;', '→'],
+    ['&quot;', '"'],
+    ['&amp;', '&'],
+    ['&#39;', "'"],
+    ['&lt;', '<'],
+    ['&gt;', '>'],
+];
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 // stripScriptBlocks is imported from html-sanitize.ts
 /**
@@ -264,7 +347,357 @@ function checkMetaTagSync(html) {
         return false;
     return true;
 }
+/**
+ * Decode common HTML entities that appear in meta keyword values.
+ * Only covers the entities actually used by the article template engine.
+ *
+ * Uses a single-pass scan to avoid double-unescaping (e.g. `&amp;lt;`
+ * becomes `&lt;`, NOT `<`). Each `&` in the input is checked once;
+ * decoded replacements are never re-scanned.
+ *
+ * @param s - String potentially containing HTML entities
+ * @returns The string with common entities decoded
+ */
+function decodeKeywordEntities(s) {
+    const parts = [];
+    let i = 0;
+    while (i < s.length) {
+        const ch = s[i] ?? '';
+        if (ch === '&') {
+            const rest = s.slice(i).toLowerCase();
+            let matched = false;
+            for (const [entity, replacement] of ENTITY_PAIRS) {
+                if (rest.startsWith(entity)) {
+                    parts.push(replacement);
+                    i += entity.length;
+                    matched = true;
+                    break;
+                }
+            }
+            if (!matched) {
+                parts.push(ch);
+                i++;
+            }
+        }
+        else {
+            parts.push(ch);
+            i++;
+        }
+    }
+    return parts.join('');
+}
+/**
+ * Normalize a keyword token for comparison: decode HTML entities,
+ * collapse arrow/dash variants, and normalize whitespace.
+ *
+ * @param s - Raw keyword token to normalize
+ * @returns Lowercased, entity-decoded, dash-normalized token
+ */
+function normalizeKeywordToken(s) {
+    let decoded = decodeKeywordEntities(s);
+    // Normalize arrow/dash variants → single canonical form
+    decoded = decoded.replace(/→/gu, '->');
+    decoded = decoded.replace(/—/gu, '-');
+    decoded = decoded.replace(/–/gu, '-');
+    // Collapse whitespace and lowercase
+    return decoded.replace(/\s+/gu, ' ').trim().toLowerCase();
+}
+/**
+ * Detect section-heading keywords that leaked into the article's meta keywords.
+ * Returns the list of banned keywords found.
+ *
+ * Decodes HTML entities (e.g. `&amp;` → `&`) and normalizes dash/arrow
+ * variants so that exact comma-separated tokens can be matched after
+ * normalization, for example "Winners &amp; Losers" matching
+ * "Winners & Losers". Combined phrases are not split on dash or arrow
+ * separators and therefore only match if the full normalized token is banned.
+ *
+ * @param html - HTML string to inspect
+ * @returns Array of section-heading keywords found in the meta tag
+ */
+function detectBannedKeywords(html) {
+    const keywordsMeta = extractMetaContent(html, 'name', 'keywords');
+    if (!keywordsMeta)
+        return [];
+    // Parse comma-separated keywords and normalize each token
+    const tokens = keywordsMeta
+        .split(',')
+        .map((k) => normalizeKeywordToken(k))
+        .filter((k) => k.length > 0);
+    const bannedNormalized = getBannedNormalized();
+    const found = [];
+    for (const token of tokens) {
+        const original = bannedNormalized.get(token);
+        if (original) {
+            found.push(original);
+        }
+    }
+    return found;
+}
+/**
+ * Test whether a character is a boundary before/after the word "class"
+ * in an HTML attribute context.
+ *
+ * @param ch - The character to test (or undefined if at string edge)
+ * @param side - Whether to check as a 'before' or 'after' boundary
+ * @returns true if the character is a valid boundary
+ */
+function isAttrBoundary(ch, side) {
+    if (!ch || ch === '')
+        return true;
+    if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r')
+        return true;
+    if (side === 'before')
+        return ch === '"' || ch === "'";
+    return ch === '=';
+}
+/**
+ * Extract the quoted value of the `class` attribute starting at a given cursor
+ * position (immediately after the word "class"). Returns `null` if the syntax
+ * is not `class = "..."` or `class = '...'`.
+ *
+ * @param tag - The full start-tag string
+ * @param cursor - Index right after the word "class" in `tag`
+ * @returns `{ value, end }` or `null`
+ */
+function extractClassValue(tag, cursor) {
+    let pos = cursor;
+    // Skip whitespace before '=' (space, tab, newline, carriage return)
+    while (pos < tag.length &&
+        (tag[pos] === ' ' || tag[pos] === '\t' || tag[pos] === '\n' || tag[pos] === '\r'))
+        pos++;
+    if (pos >= tag.length || tag[pos] !== '=')
+        return null;
+    pos++; // skip '='
+    // Skip whitespace before opening quote
+    while (pos < tag.length &&
+        (tag[pos] === ' ' || tag[pos] === '\t' || tag[pos] === '\n' || tag[pos] === '\r'))
+        pos++;
+    if (pos >= tag.length)
+        return null;
+    const quote = tag[pos];
+    if (quote !== '"' && quote !== "'")
+        return null;
+    const valueStart = pos + 1;
+    const valueEnd = tag.indexOf(quote, valueStart);
+    if (valueEnd === -1)
+        return null;
+    return { value: tag.slice(valueStart, valueEnd), end: valueEnd + 1 };
+}
+/**
+ * Check whether an HTML start tag has a specific class token (whitespace-tokenized).
+ * Handles both single-quoted and double-quoted class attributes.
+ *
+ * @param startTag - An opening HTML tag string (e.g. `<span class="metric-value foo">`)
+ * @param token - The class token to look for (e.g. `metric-value`)
+ * @returns true if the class attribute contains the exact token
+ */
+function hasClassToken(startTag, token) {
+    const lowerTag = startTag.toLowerCase();
+    let searchFrom = 0;
+    while (searchFrom < lowerTag.length) {
+        const classPos = lowerTag.indexOf('class', searchFrom);
+        if (classPos === -1)
+            return false;
+        const before = classPos > 0 ? lowerTag[classPos - 1] : undefined;
+        const after = classPos + 5 < lowerTag.length ? lowerTag[classPos + 5] : undefined;
+        if (!isAttrBoundary(before, 'before') || !isAttrBoundary(after, 'after')) {
+            searchFrom = classPos + 5;
+            continue;
+        }
+        const extracted = extractClassValue(startTag, classPos + 5);
+        if (!extracted) {
+            searchFrom = classPos + 5;
+            continue;
+        }
+        const tokens = extracted.value.split(/\s+/u).filter((t) => t.length > 0);
+        if (tokens.includes(token))
+            return true;
+        searchFrom = extracted.end;
+    }
+    return false;
+}
+/**
+ * Detect metric values showing "0%" in pipeline-health / pipeline-metrics
+ * containers, which indicate no-data conditions that should not be rendered
+ * as real dashboard metrics.
+ *
+ * Only flags `0%` inside elements whose surrounding context includes a
+ * `pipeline-metrics` or `pipeline-health` class, avoiding false positives
+ * on legitimate trend-panel change indicators (e.g. week-over-week 0%).
+ *
+ * @param html - HTML string to inspect
+ * @returns Number of 0% pipeline metric values found
+ */
+function detectZeroPercentMetrics(html) {
+    // Use indexOf-based search to avoid regex backtracking (ReDoS-safe)
+    let count = 0;
+    let searchFrom = 0;
+    const zeroValue = '0%';
+    const lowerHtml = html.toLowerCase();
+    while (searchFrom < html.length) {
+        const tagStart = html.indexOf('<', searchFrom);
+        if (tagStart === -1)
+            break;
+        const tagClose = html.indexOf('>', tagStart);
+        if (tagClose === -1)
+            break;
+        const startTag = html.slice(tagStart, tagClose + 1);
+        // Only check elements that have the 'metric-value' class token
+        if (hasClassToken(startTag, 'metric-value')) {
+            const contentStart = tagClose + 1;
+            const nextTag = html.indexOf('<', contentStart);
+            if (nextTag === -1)
+                break;
+            const textContent = html.slice(contentStart, nextTag).trim();
+            if (textContent === zeroValue && isInPipelineContext(lowerHtml, tagStart)) {
+                count++;
+            }
+            searchFrom = nextTag;
+            continue;
+        }
+        searchFrom = tagClose + 1;
+    }
+    return count;
+}
+/**
+ * Check whether a position in the HTML is inside a pipeline-health/metrics context.
+ * Looks backward up to 2000 chars for pipeline marker class names.
+ *
+ * If a `trend-panel` marker appears *after* the nearest pipeline marker,
+ * the element is inside a trend panel (not pipeline), so return false.
+ * This avoids flagging legitimate WoW/MoM 0% deltas rendered by
+ * `buildTrendPanel` that happen to fall within the look-behind window.
+ *
+ * @param lowerHtml - Lowercase HTML string
+ * @param position - Current scan position
+ * @returns true if inside a pipeline context
+ */
+function isInPipelineContext(lowerHtml, position) {
+    const precedingHtml = lowerHtml.slice(Math.max(0, position - PIPELINE_CONTEXT_LOOKBEHIND_CHARS), position);
+    const pipelineMetricsPos = precedingHtml.lastIndexOf('pipeline-metrics');
+    const pipelineHealthPos = precedingHtml.lastIndexOf('pipeline-health');
+    const lastPipelinePos = Math.max(pipelineMetricsPos, pipelineHealthPos);
+    if (lastPipelinePos === -1)
+        return false;
+    // If a trend-panel marker appears after the pipeline marker, the element
+    // is inside a trend panel, not the pipeline panel.
+    const trendPanelPos = precedingHtml.lastIndexOf('trend-panel');
+    if (trendPanelPos !== -1 && trendPanelPos > lastPipelinePos)
+        return false;
+    return true;
+}
+/**
+ * Strip HTML tags from a string using a simple character scanner.
+ * ReDoS-safe alternative to regex-based tag removal.
+ *
+ * @param input - HTML string to strip tags from
+ * @returns Plain text content with tags removed
+ */
+function stripHtmlTags(input) {
+    const parts = [];
+    let inTag = false;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i] ?? '';
+        if (ch === '<') {
+            inTag = true;
+        }
+        else if (ch === '>') {
+            inTag = false;
+        }
+        else if (!inTag) {
+            parts.push(ch);
+        }
+    }
+    return parts.join('');
+}
+/**
+ * Evaluate whether a section's inner HTML has enough meaningful content.
+ *
+ * @param innerHtml - The HTML content between `<section>` and `</section>` tags
+ * @returns true if the section is empty or near-empty
+ */
+function isSectionEmpty(innerHtml) {
+    const plainText = stripHtmlTags(innerHtml).replace(/\s+/gu, ' ').trim();
+    return plainText.length < MIN_SECTION_CONTENT_LENGTH;
+}
+/**
+ * Find the next `<section` open or `</section>` close tag from a given cursor.
+ * Returns `{ type, pos }` or `null` if no more section tags found.
+ *
+ * @param lowerHtml - Lowercase HTML string
+ * @param cursor - Start position
+ * @returns Tag event or null
+ */
+function findNextSectionTag(lowerHtml, cursor) {
+    const nextOpen = lowerHtml.indexOf('<section', cursor);
+    const nextClose = lowerHtml.indexOf('</section>', cursor);
+    if (nextOpen === -1 && nextClose === -1)
+        return null;
+    const openFirst = nextOpen !== -1 && (nextClose === -1 || nextOpen < nextClose);
+    return openFirst ? { type: 'open', pos: nextOpen } : { type: 'close', pos: nextClose };
+}
+/**
+ * Count empty `<section>` elements — those with little or no visible content.
+ * An empty section contains only whitespace or very short boilerplate text.
+ * Uses a stack-based scanner to correctly handle nested `<section>` elements.
+ *
+ * @param html - HTML string to inspect
+ * @returns Number of empty sections found
+ */
+function countEmptySections(html) {
+    const lowerHtml = html.toLowerCase();
+    let count = 0;
+    const stack = [];
+    let cursor = 0;
+    let event = findNextSectionTag(lowerHtml, cursor);
+    while (event) {
+        if (event.type === 'open') {
+            const tagEnd = html.indexOf('>', event.pos);
+            if (tagEnd === -1)
+                break;
+            stack.push(tagEnd + 1);
+            cursor = tagEnd + 1;
+        }
+        else {
+            if (stack.length > 0) {
+                const contentStart = stack[stack.length - 1] ?? 0;
+                stack.pop();
+                if (isSectionEmpty(html.slice(contentStart, event.pos))) {
+                    count++;
+                }
+            }
+            cursor = event.pos + '</section>'.length;
+        }
+        event = findNextSectionTag(lowerHtml, cursor);
+    }
+    return count;
+}
 // ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Collect warnings from machine-enforceable article quality gates.
+ * Extracted to keep `validateArticleContent` within cognitive-complexity limits.
+ *
+ * @param html - Complete HTML string
+ * @param warnings - Mutable warnings array to append to
+ */
+function collectQualityGateWarnings(html, warnings) {
+    // Keyword quality: detect section-heading keywords leaked into meta tags
+    const bannedKeywords = detectBannedKeywords(html);
+    if (bannedKeywords.length > 0) {
+        warnings.push(`Keywords contain ${bannedKeywords.length} section heading(s) that should not be used as keywords: ${bannedKeywords.join(', ')}`);
+    }
+    // Dashboard metric quality: detect 0% metrics rendered as real data
+    const zeroMetricCount = detectZeroPercentMetrics(html);
+    if (zeroMetricCount > 0) {
+        warnings.push(`Dashboard renders ${zeroMetricCount} metric(s) showing "0%" — this likely indicates no-data, not a real score. Omit the dashboard when data is unavailable.`);
+    }
+    // Empty section detection: flag sections with no meaningful content
+    const emptySectionCount = countEmptySections(html);
+    if (emptySectionCount > 0) {
+        warnings.push(`Article contains ${emptySectionCount} empty or near-empty <section> element(s) that should be removed`);
+    }
+}
 /**
  * Validate the quality of a generated article.
  *
@@ -287,7 +720,7 @@ export function validateArticleContent(html, language, articleType) {
     const errors = [];
     // Word count check
     const wordCount = countWordsInHtml(html);
-    const minWords = MIN_WORD_COUNTS[articleType] !== undefined ? MIN_WORD_COUNTS[articleType] : DEFAULT_MIN_WORDS;
+    const minWords = MIN_WORD_COUNTS[articleType] ?? DEFAULT_MIN_WORDS;
     if (wordCount < minWords) {
         warnings.push(`Content too short: ${wordCount} words (minimum ${minWords} for "${articleType}")`);
     }
@@ -336,6 +769,8 @@ export function validateArticleContent(html, language, articleType) {
     }
     // Extended validation: cross-reference density, stakeholder balance, temporal coverage
     collectExtendedValidationWarnings(html, warnings);
+    // Machine-enforceable article quality gates
+    collectQualityGateWarnings(html, warnings);
     return {
         valid: errors.length === 0,
         warnings,

package/scripts/utils/file-utils.js

@@ -59,13 +59,19 @@ export function groupArticlesByLanguage(articles, languages) {
     }
     for (const article of articles) {
         const parsed = parseArticleFilename(article);
-        if (parsed && grouped[parsed.lang] !== undefined) {
-            grouped[parsed.lang].push(parsed);
+        if (parsed) {
+            const bucket = grouped[parsed.lang];
+            if (bucket) {
+                bucket.push(parsed);
+            }
         }
     }
     // Sort by date (newest first)
     for (const lang in grouped) {
-        grouped[lang].sort((a, b) => b.date.localeCompare(a.date));
+        const bucket = grouped[lang];
+        if (bucket) {
+            bucket.sort((a, b) => b.date.localeCompare(a.date));
+        }
     }
     return grouped;
 }
@@ -89,8 +95,7 @@ export function formatSlug(slug) {
  */
 export function getModifiedDate(filepath) {
     const stats = fs.statSync(filepath);
-    // split('T') on an ISO string always produces at least one element
-    return stats.mtime.toISOString().split('T')[0];
+    return stats.mtime.toISOString().slice(0, 10);
 }
 /**
  * Format date for article slug
@@ -99,8 +104,7 @@ export function getModifiedDate(filepath) {
  * @returns Formatted date string (YYYY-MM-DD)
  */
 export function formatDateForSlug(date = new Date()) {
-    // split('T') on an ISO string always produces at least one element
-    return date.toISOString().split('T')[0];
+    return date.toISOString().slice(0, 10);
 }
 /**
  * Calculate read time estimate from content

package/scripts/utils/political-risk-assessment.js

@@ -529,6 +529,9 @@ function synthesiseOverallRisk(risks, assessmentId, date) {
     }
     // Safe: risks.length > 0 is guaranteed by the guard above
     const firstRisk = risks[0];
+    if (!firstRisk) {
+        throw new Error(`Invariant violation: risks[0] was undefined for non-empty risks array in assessment ${assessmentId} on ${date}`);
+    }
     const maxRisk = risks.reduce((max, r) => (r.riskScore > max.riskScore ? r : max), firstRisk);
     // Count confidence levels to pick the dominant one
     const confidenceCounts = { high: 0, medium: 0, low: 0 };

package/scripts/utils/world-bank-data.js

@@ -171,7 +171,7 @@ function splitCSVLine(line) {
     let current = '';
     let inQuotes = false;
     for (let i = 0; i < line.length; i++) {
-        const ch = line[i];
+        const ch = line[i] ?? '';
         if (ch === '"') {
             if (inQuotes && i + 1 < line.length && line[i + 1] === '"') {
                 // RFC 4180 escaped quote: "" → literal "
@@ -209,11 +209,11 @@ export function parseWorldBankCSV(csvText) {
     if (lines.length < 2) {
         return [];
     }
-    const headers = splitCSVLine(lines[0]).map((h) => h.toLowerCase());
+    const headers = splitCSVLine(lines[0] ?? '').map((h) => h.toLowerCase());
     const colMap = Object.fromEntries(Object.entries(HEADER_ALIASES).map(([key, aliases]) => [key, findColumnIndex(headers, aliases)]));
     const results = [];
     for (let i = 1; i < lines.length; i++) {
-        const cols = splitCSVLine(lines[i]);
+        const cols = splitCSVLine(lines[i] ?? '');
         const rawValue = readCol(cols, colMap['value'] ?? -1);
         const parsedValue = rawValue !== '' ? Number(rawValue) : null;
         const yearStr = readCol(cols, colMap['date'] ?? -1);