🏛️ EU Parliament Monitor

European Parliament Intelligence Platform
Monitor political activity with systematic transparency

European Parliament Intelligence Platform — an automated multi-language news platform that monitors EU Parliament activities with 14-language support, covering plenary sessions, committee reports, propositions, and breaking news. 📂 Repository • ✨ Features • 📚 Documentation

📦 Quick Start

npm install euparliamentmonitor

import {
  EuropeanParliamentMCPClient,
  generateArticleHTML,
  scoreArticleQuality,
  ALL_LANGUAGES,
} from 'euparliamentmonitor';

Key capabilities:

• 🏛️ EU Parliament MCP Client — Connect to European Parliament open data via Model Context Protocol
• 📰 News Generation — Generate multi-language articles (14 languages) from parliamentary data
• 🔍 Political Intelligence — Voting anomaly detection, coalition analysis, threat assessment
• 📊 Article Quality — Score and validate generated content with comprehensive quality metrics
• 🌍 Multilingual — Full i18n support: EN, SV, DA, NO, FI, DE, FR, ES, NL, AR, HE, JA, KO, ZH

Explore the live platform — 🌐 euparliamentmonitor.com · 🧠 Political Intelligence Hub (methodology + artifact transparency, all 14 languages) · 🗺️ Site Map (every page, every language) · 📔 API Reference

📦 About this package — euparliamentmonitor is the open-source TypeScript library powering euparliamentmonitor.com, an automated European Parliament transparency platform that publishes daily AI-generated, Economist-style political-intelligence articles in 14 languages. The package bundles the EU Parliament MCP client (60+ open-data tools — plenary sessions, committee reports, voting records, parliamentary questions, adopted texts, procedures, MEPs, declarations), the deterministic article aggregator (analysis-artifact → Markdown → HTML, with 14-language hreflang and shared site chrome), the political-intelligence analytics (voting-anomaly detection, coalition dynamics, MEP influence scoring, OSINT correlation), and the multi-language renderer with WCAG 2.1 AA accessibility, structured data, and SEO-ready sitemap generation. Designed for civic-tech, data-journalism, OSINT, and democratic-transparency use cases. ISO 27001 / NIST CSF 2.0 / CIS Controls v8.1 / GDPR / NIS2 / EU CRA aligned.

Published with npm provenance for supply chain security. SLSA Level 3 build attestations included.

🎯 Status Badges

Workflow Status

Documentation & Reports

🌐 Live Site — Explore the Platform

The published platform at euparliamentmonitor.com is the audience-facing companion to this npm package. Two hub pages give the fastest entry into the daily output and the underlying tradecraft:

🧠 Political Intelligence Hub Audit-ready transparency layer behind every published article. Indexes the 10-step AI-driven analysis protocol, the 39 artifact templates, the per-artifact methodologies (BLUF, Admiralty WEP source-grading, SAT, Heuer's ACH, OSINT tradecraft), and links every run-level artifact under analysis/daily/<date>/<slug>/ directly to GitHub so readers can verify the analysis behind the prose. Available in all 14 supported languages.

🗺️ Site Map Human-readable index of every page on the platform — landing pages, news articles, and technical documentation — across all 14 languages (EN, SV, DA, NO, FI, DE, FR, ES, NL, AR, HE, JA, KO, ZH). Best starting point for SEO crawlers, audience navigation, and discovering the latest articles. Companion to the machine-readable sitemap.xml and per-language sitemap_<lang>.html variants.

📚 Documentation Hub

📖 Quick Links:

• 🌐 Live Site - Public news platform (14 languages, daily AI-generated articles)
• 🧠 Political Intelligence Hub - Methodology + artifact transparency layer
• 🗺️ Site Map - All pages across all 14 languages
• 📘 Architecture Documentation - Complete security architecture with C4 diagrams
• 📗 Security Flows - Process flows with security controls
• 📙 Data Model - Data structures and API integration
• 📕 Release Process - How to create releases
• 📔 API Documentation - TypeDoc-generated API reference
• 📓 Test Coverage - Interactive coverage report

🤖 Agentic Pipeline:

• Agent Catalog — custom Copilot agents (analysis producers / consumers / gh-aw infrastructure)
• Skills Library — shared skills (security, compliance, intelligence, gh-aw)
• Prompt Library — 10-file bounded-context prompt set (00→09) + npm run lint:prompts drift-guard
• Workflows + WORKFLOWS.md — 9 news-*.md agentic workflows (8 unified news-<type>.md + news-translate.md) + CI workflows
• Analysis Chain — 5-stage pipeline (Data → Analysis → Completeness Gate → Article → Single PR), methodologies, 39 templates, quality thresholds

🔒 ISMS Compliance:

• 🛡️ Hack23 ISMS Framework - Information Security Management System
• 🔐 Secure Development Policy - Development standards
• 📋 Classification Framework - CIA triad classification

Current Status

MCP Server Integration: The project uses the European-Parliament-MCP-Server v1.2.15 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)
• Agentic Workflows: 9 unified gh-aw markdown workflows — 8 article types (news-<type>.md, Stages A → B → C → D → E in one session) + news-translate.md (14-language flush translation) — compiled with gh-aw v0.69.3 (pin in .github/workflows/compile-agentic-workflows.yml) to .lock.yml for automated news generation with AI-driven political intelligence analysis. See .github/workflows/README.md.
• Analysis-Artifact-Driven Article Pipeline: Agents author the full Stage-B analysis-artifact set (analysis/daily/<date>/<slug>/, 39 structured templates per run; repeat same-day runs reuse the folder and append to manifest.json.history[]) and commit it; the deterministic aggregator (src/aggregator/**, invoked via npm run generate-article -- --run <analysis-run-dir> or npm run generate-article:all for batch regen) then walks manifest.json, cleans each artifact, and emits the final Markdown source + HTML with the shared site chrome (stacked header + embedded 14-language switcher + TOC sidebar + footer stats) and 14-language <link rel="alternate" hreflang> entries. There is no AI-authored HTML step; article quality is guaranteed editorially at the Stage-C completeness review over the artifact markdown. See analysis/README.md and analysis/methodologies/ai-driven-analysis-guide.md.
• Fallback Mode: News generation can work with reduced data when EP API endpoints are temporarily unavailable
• Environment Variable: Set USE_EP_MCP=false to disable MCP client connection attempts

EU Parliament Monitor is an automated news generation platform that monitors European Parliament activities and generates multi-language news articles covering:

• Week Ahead: Preview of upcoming parliamentary events and committee meetings
• Committee Reports: Analysis of committee activities and decisions
• Propositions: Government and parliamentary legislative proposals
• Motions: Parliamentary motions and resolutions
• Breaking News: Rapid-response coverage of significant developments

Features

• 📰 Automated News Generation: Generate news articles about EU Parliament activities
• 🌍 Multi-Language Support: 14 languages including English, Swedish, German, French, Spanish, Arabic, Japanese, and more
• 📅 Week Ahead Coverage: Preview upcoming parliamentary events
• 🤖 GitHub Actions Integration: Automated daily news generation
• 📊 SEO Optimized: Proper metadata, structured data, and sitemap generation
• ✅ Code Quality: ESLint, Prettier, and automated quality gates
• 🌐 IMF-grade Economic Context: IMF-primary citations are the editorial standard for every policy article — see analysis/imf/README.md and analysis/methodologies/imf-indicator-mapping.md. World Bank is retained only for non-economic indicators (health, education, social, environment, demographics, defence, agriculture, innovation, governance).

🔒 Security Architecture

EU Parliament Monitor implements security-by-design with comprehensive security controls and ISMS compliance.

Security Documentation

• 📋 Security Architecture - Complete security implementation overview with C4 diagrams, threat model, and compliance mapping
• 🚀 Future Security Architecture - Security enhancement roadmap (2026-2027)
• 📊 Data Model - Data structures and European Parliament API integration
• 📈 Security Flowcharts - Detailed process flows with security controls

Security Posture

Project Classification (per ISMS Classification Framework and Open Source Policy):

• Confidentiality: Public (Level 1) - European Parliament open data
• Integrity: Medium (Level 2) - News accuracy critical for democratic transparency
• Availability: Medium (Level 2) - Daily updates expected, 24h RTO acceptable
• RTO: 24 hours | RPO: 1 day (daily generation schedule)
• Business Impact: Low financial, Medium operational, Medium reputational
• Strategic Value: Democratic transparency, open civic technology leadership

Key Security Controls:

• ✅ Minimal Attack Surface: Static site, no databases, no server-side execution
• ✅ Automated Security: CodeQL SAST, Dependabot SCA, npm audit
• ✅ Supply Chain Security: SHA-pinned GitHub Actions, SBOM generation
• ✅ Input Validation: Multi-layer XSS prevention, HTML sanitization
• ✅ Infrastructure Security: GitHub-hosted ephemeral runners, HTTPS enforcement
• ✅ Compliance: ISO 27001, GDPR, NIS2, EU CRA aligned

Security Metrics:

• Zero known vulnerabilities (npm audit clean)
• 82%+ code coverage with security tests
• 100% dependency scanning coverage
• 0 CodeQL critical/high findings

ISMS Alignment

This project follows Hack23 ISMS Secure Development Policy:

• ✅ Security architecture documentation (C4 models with Mermaid)
• ✅ Threat modeling (STRIDE analysis)
• ✅ Security testing (SAST, SCA, unit tests)
• ✅ Compliance mapping (ISO 27001, GDPR, NIS2)

🤝 Community & Governance

EU Parliament Monitor is an open source project with transparent governance and community standards.

Open Source Standards

• Contributing Guide - Development workflow, code standards, and contribution guidelines
• Code of Conduct - Community standards based on Contributor Covenant 2.1
• Security Policy - Vulnerability disclosure and security practices
• Authors & Contributors - Recognition of project contributors
• License - Apache License 2.0 full text

Community Channels

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions and community discussion
• Security: security@hack23.com for vulnerability reports
• Conduct: conduct@hack23.com for Code of Conduct issues

Governance Compliance

This project adheres to:

• ✅ OpenSSF Best Practices: Following CII Best Practices criteria
• ✅ ISMS Compliance: Aligned with Hack23 ISMS policies
• ✅ Transparent Development: Public repository, open discussions
• ✅ Security First: Comprehensive security disclosure policy

Code Quality & Testing

EU Parliament Monitor maintains high code quality standards with comprehensive testing:

Code Quality

• ESLint: Comprehensive linting with security, complexity, and documentation checks
• Prettier: Consistent code formatting across all JavaScript files
• Pre-commit Hooks: Automatic linting and formatting before every commit
• CI/CD Quality Gates: Automated checks on every pull request
• TypeDoc/JSDoc: Complete documentation for all functions

Code Standards: See docs/CODE_STANDARDS.md for detailed coding guidelines.

Testing Infrastructure

Comprehensive test suite with Vitest and Playwright covering all functionality:

Unit & Integration Tests (Vitest)

• Unit Tests: Article generation, MCP client, index/sitemap generation
• Integration Tests: Full workflows, MCP integration, multi-language support
• Coverage: ≥80% line coverage, ≥75% branch coverage
• Test Count: 169+ tests covering critical paths

# Run unit & integration tests
npm test

# Run with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run with UI (browser interface)
npm run test:ui

End-to-End Tests (Playwright)

• E2E Tests: Complete user experience validation
• Cross-Browser: Chromium, Firefox, WebKit
• Mobile Support: Mobile Chrome, Mobile Safari
• Accessibility: WCAG 2.1 AA compliance with axe-core
• Responsive Design: Multiple viewport sizes
• Test Count: 60+ E2E tests covering user journeys

# Run E2E tests
npm run test:e2e

# Run with UI (interactive)
npm run test:e2e:ui

# Run in headed mode (see browser)
npm run test:e2e:headed

# View test report
npm run test:e2e:report

Testing Documentation:

• test/README.md - Unit & integration tests
• e2e/README.md - E2E testing guide

Custom Agents

EU Parliament Monitor includes 8 specialized GitHub Copilot custom agents to streamline development:

• 🤖 product-task-agent - Product specialist for issue creation and coordination
• 📰 news-journalist - The Economist-style European Parliament reporting
• 🎨 frontend-specialist - HTML5/CSS3/WCAG 2.1 AA UI/UX expert
• 🔄 data-pipeline-specialist - European Parliament MCP integration expert
• ⚙️ devops-engineer - CI/CD and GitHub Actions automation
• 🔒 security-architect - ISMS, GDPR, NIS2 compliance expert
• 📚 documentation-architect - C4 models and architecture docs
• ✅ quality-engineer - Testing, validation, and accessibility

Usage Example:

# Use product-task-agent to analyze repository and create improvement issues
@product-task-agent analyze the multi-language support and create issues for any gaps

# Use news-journalist to generate content
@news-journalist create a week-ahead article for the upcoming plenary session

# Use frontend-specialist for UI improvements
@frontend-specialist make the language switcher fully keyboard accessible

Learn More: See Custom Agents Documentation for detailed agent capabilities, usage patterns, and examples.

Languages Supported

• Nordic: English (en), Swedish (sv), Danish (da), Norwegian (no), Finnish (fi)
• EU Core: German (de), French (fr), Spanish (es), Dutch (nl)
• Middle East: Arabic (ar), Hebrew (he)
• East Asia: Japanese (ja), Korean (ko), Chinese (zh)

Requirements

• Node.js: Version 25 or higher
• npm: Version 10 or higher (comes with Node.js 25)
• Git: For cloning the repository

You can verify your Node.js version with:

node --version  # Should be v25.x.x or higher
npm --version   # Should be 10.x.x or higher

Installation

As an npm Package

npm install euparliamentmonitor

TypeScript / ES Module Usage

import {
  // MCP Client for EU Parliament data
  EuropeanParliamentMCPClient,
  getEPMCPClient,
  // Intelligence index (cross-article relationships)
  buildIndexFromEntries,
  findRelatedArticles,
  generateCrossReferences,
  // Article generation (aggregator pipeline)
  generateArticle,
  aggregateAnalysisRun,
  renderMarkdown,
  // Multi-language support (14 languages)
  ALL_LANGUAGES,
  LANGUAGE_NAMES,
} from 'euparliamentmonitor';

// Or import specific modules for tree-shaking
import { EuropeanParliamentMCPClient } from 'euparliamentmonitor/mcp/ep-mcp-client';
import type { ArticleCategory, LanguageCode } from 'euparliamentmonitor/types';

From Source (Development)

# Clone the repository
git clone https://github.com/Hack23/euparliamentmonitor.git
cd euparliamentmonitor

# Install dependencies
npm install

Optional: European Parliament MCP Server

For real EU Parliament data integration, install the MCP server:

# Clone the MCP server repository
git clone https://github.com/Hack23/European-Parliament-MCP-Server.git
cd European-Parliament-MCP-Server

# Install dependencies and build
npm install
npm run build

# The server will be available at dist/index.js
# You can install it globally or reference the path

Configure the MCP server path in environment variables:

export EP_MCP_SERVER_PATH="/path/to/European-Parliament-MCP-Server/dist/index.js"

Note: The MCP server is currently in development. News generation works without it using placeholder content.

Usage

Generate News Articles

Agentic workflows generate articles automatically. For manual article generation from an analysis run:

# Render one article from a specific analysis run directory
npm run generate-article -- --run analysis/daily/2025-01-01/breaking

# Regenerate EVERY committed analysis run in one pass (skips runs whose
# manifest.json has no valid articleType; collision-suffixes same-date /
# same-type runs with a sanitised runId)
npm run generate-article:all

# Only regenerate runs from a given date onward
npm run generate-article -- --all --since 2026-04-01

Each invocation writes:

• news/<slug>.en.md — aggregated Markdown (provenance block + 19-section ordered artifact set + Tradecraft References appendix + Analysis Index appendix)
• news/<slug>-<lang>.html — 14 language variants, each wrapped in the shared site chrome (stacked header with embedded language switcher, article-level Table of Contents sidebar, shared footer with live article-count stats)

The aggregator lives under src/aggregator/ — see the aggregator pipeline section of the architecture doc for the full data flow.

Editorial-highlight metadata resolver

The <title> / <meta description> / Open Graph / Twitter / JSON-LD NewsArticle fields for every article are resolved by src/aggregator/article-metadata.ts through a 5-tier priority ladder:

1. Manifest override — the Stage-B agent writes one of these keys in manifest.json when it has an editorial headline:

   {
     "articleType": "breaking",
     // String form — applied to all 14 language variants (recommended
     // when only an English headline is available):
     "title": "Banking Union Breakthrough and Anti-Corruption Landmark",
     "description": "The plenary closes a six-year debate and triggers immediate criticism from two national delegations about implementation timelines.",
     // OR per-language form when translations already exist:
     "title": { "en": "…", "sv": "…", "de": "…" },
     "description": { "en": "…", "sv": "…" }
   }

2. First artefact H1 — the aggregator walks the manifest's ordered artefact list (intelligence/synthesis-summary.md, executive-summary.md, breaking-news-analysis.md, …) and promotes the first non-generic # … heading.

3. Aggregated-markdown H1 — any non-generic top-level heading in the rendered Markdown.

4. First strong prose paragraph — with a tightened leak filter that blocks mermaid %%{init} blocks, title … directives, emoji-banner metadata, and Analysis Date: / Classification: / Run: / Window: / Purpose: / BLUF (ICD-203): style rows.

5. Localized template — *_TITLES(date) from src/constants/language-articles.ts — last resort when no editorial content exists at all.

Downstream generators (news-indexes.ts, sitemap.ts, political-intelligence cards, RSS) call extractArticleMeta() in src/utils/file-utils.ts, which reads the <head><title> value (with the — EU Parliament Monitor suffix stripped) as the primary title, so the resolver's output propagates everywhere without separate code changes in each generator.

Backport SEO metadata into existing articles

scripts/backport-article-seo.js rewrites <title>, the meta description, Open Graph, Twitter, and JSON-LD headline/description for every already-rendered news/*-<lang>.html file by extracting the first editorial H1 and first strong prose paragraph from the article body itself. The rewrite is idempotent — re-running over a backported file is a byte-identical no-op — and the article body is never modified.

# Preview the change-set (dry-run is the default; prints a per-article-
# type summary and up to 12 sample before/after diffs):
node scripts/backport-article-seo.js

# Write changes:
node scripts/backport-article-seo.js --apply

# Scope to a subset of article types:
node scripts/backport-article-seo.js --apply --only breaking,motions

# Use a non-default news directory:
node scripts/backport-article-seo.js --apply --dir news

After backporting, regenerate the downstream surfaces that depend on article metadata:

node scripts/generators/news-indexes.js   # 14 language index pages
node scripts/generators/sitemap.js        # 14 sitemap HTMLs + sitemap.xml + rss.xml

Generate Indexes and Sitemap

# Generate per-run news index pages (consumed by the aggregator's
# transparency footer and political-intelligence.html)
npm run generate-news-indexes

# Generate sitemap.xml, sitemap_<lang>.html, and political-intelligence_<lang>.html
# (14 language-specific sitemap pages + 14 language-specific Political Intelligence
#  pages that index every methodology, template, and daily analysis run)
npm run generate-sitemap

Local Development

# Serve the site locally
npm run serve

# Open http://localhost:8080 in your browser

Same-Origin JS Bundle (Mermaid + Chart.js + D3)

The static site loads every executable bundle from same-origin js/vendor/ under a strict script-src 'self' CSP — no external CDN. Vendored libraries are copied from node_modules/ at build time:

npm run copy-vendor    # writes js/vendor/{chart.umd.min.js,d3.min.js,…,mermaid/}

The CI deploy workflow (deploy-s3.yml) runs copy-vendor before aws s3 sync and includes both *.js and *.mjs files (Mermaid 11 ships as code-split ESM under js/vendor/mermaid/chunks/). If you add a new diagram type to a template, no extra wiring is needed — the chunk loader is part of the vendored bundle.

Stage-C Analysis Validator

Before opening an article PR, validate the analysis run completeness:

npm run validate-analysis -- analysis/daily/<date>/<run-dir>

The validator enforces per-artifact line floors, mandatory Mermaid diagrams, Admiralty/WEP/SAT/BLUF tradecraft signals, required H2 sections, and placeholder leakage. RED output ⇒ Pass-3 the offending artifacts; never ship an article without a green gate. See .github/prompts/03-analysis-completeness-gate.md.

Project Structure

euparliamentmonitor/
├── .github/
│   ├── agents/                      # Custom GitHub Copilot agents
│   ├── workflows/                   # CI/CD workflow configurations
│   └── release-drafter.yml          # Release notes configuration
├── src/                             # TypeScript source (compiles to scripts/)
│   ├── constants/                   # Language data, configuration
│   ├── generators/                  # News, index, sitemap generators
│   ├── mcp/                         # European Parliament MCP client
│   ├── templates/                   # HTML article templates
│   ├── types/                       # Shared TypeScript interfaces
│   └── utils/                       # File utilities, metadata
├── scripts/                         # Compiled JavaScript output
│   ├── constants/                   # Compiled constants
│   ├── generators/                  # Compiled generators
│   ├── mcp/                         # Compiled MCP client
│   ├── templates/                   # Compiled templates
│   ├── types/                       # Compiled type definitions
│   └── utils/                       # Compiled utilities
├── news/                            # Generated news articles
│   └── metadata/                    # Generation metadata
├── test/                            # Vitest unit & integration tests
├── e2e/                             # Playwright E2E tests
├── docs/                            # Generated documentation
├── styles.css                       # Article styling
├── index-{lang}.html                # Language-specific index pages
├── typedoc.json                     # TypeDoc configuration
├── tsconfig.json                    # TypeScript configuration
├── sitemap.xml                      # SEO sitemap with hreflang alternates
├── sitemap.html                     # Human-readable sitemap (English)
├── sitemap_{lang}.html              # Per-language human-readable sitemaps
├── political-intelligence.html      # Index of every methodology + template + daily analysis run
├── political-intelligence_{lang}.html # Localized political-intelligence pages
└── package.json                     # Project dependencies

CI/CD & Automation

GitHub Actions Workflows

The repository includes comprehensive GitHub Actions workflows for automation and quality assurance:

📰 News Generation

• Schedule: Runs daily at 06:00 UTC
• Manual Trigger: Can be triggered manually with custom parameters
• Automatic Commit: Commits and pushes generated articles automatically
• Workflow: .github/workflows/news-generation.yml

Workflow Inputs:

• article_types: Comma-separated list of article types (default: week-ahead)
• languages: Languages to generate (en, eu-core, all, or custom list)
• force_generation: Force generation even if recent articles exist

🏷️ PR Labeling

• Automatic: Labels PRs based on file changes
• Configuration: .github/labeler.yml
• Workflow: .github/workflows/labeler.yml
• Setup: Run .github/workflows/setup-labels.yml once to create all labels

📦 Release Management

• Automated Release Notes: Via Release Drafter
• Semantic Versioning: Based on PR labels
• SBOM & Attestations: Security compliance with artifact attestations
• Workflow: .github/workflows/release.yml
• Configuration: .github/release-drafter.yml

🔒 Security Scanning

• CodeQL: Automated security analysis on push, PR, and weekly schedule
• OpenSSF Scorecard: Supply chain security assessment (weekly, on branch protection changes)
• Dependabot: Weekly dependency updates for npm and GitHub Actions
• Dependency Review: Vulnerability scanning on pull requests
• Vulnerability Scanning: Automated npm audit in PR validation
• Workflows: .github/workflows/codeql.yml, .github/workflows/scorecards.yml, .github/dependabot.yml, .github/workflows/dependency-review.yml

🏆 Compliance & Quality

• REUSE Compliance: License header verification (FSFE REUSE specification)
• SonarCloud Analysis: Automatic server-side code quality, security vulnerabilities, and technical debt tracking
• SLSA Provenance: Level 3 build attestations with SBOM generation on releases
• Workflows: .github/workflows/reuse.yml, .github/workflows/release.yml

✅ Test & Validation

• HTML Validation: Automated htmlhint checks
• Functional Tests: News generation, index, and sitemap validation
• Security Checks: npm audit for vulnerabilities
• Workflow: .github/workflows/test-and-report.yml

📊 Evidence: See Workflow Status Badges at top of README.

Workflow Status Badges

Core Workflows:

Security Workflows:

Compliance Workflows:

Manual Release Process

To create a new release:

1. Go to Actions → Release workflow
2. Click Run workflow
3. Enter version (e.g., v1.0.0)
4. Select if pre-release
5. The workflow will:
   • Run validation and tests (169 unit tests, E2E tests)
   • Generate API documentation (TypeDoc)
   • Generate test coverage reports (Vitest HTML)
   • Generate E2E test reports (Playwright)
   • Create documentation index
   • Commit documentation to main branch
   • Generate SBOM and attestations (SLSA Level 3)
   • Create GitHub release with artifacts
   • Update release notes automatically

🔒 ISMS Evidence:

• Release Workflow - Complete automation
• SLSA Attestations - Build provenance
• Release Process Guide - Step-by-step documentation

Documentation as Code

Every release automatically generates comprehensive documentation:

Documentation	Description	Link
API Documentation	TypeDoc-generated API reference from TypeScript source	View Docs
Test Coverage	Interactive Vitest coverage reports (82%+)	View Coverage
E2E Test Reports	Playwright test results with screenshots	View Report
Documentation Index	Beautiful hub linking all reports	View Index

📋 How It Works:

1. Release workflow runs all tests
2. Generates API docs with TypeDoc
3. Copies coverage reports to docs/
4. Creates documentation index page
5. Commits everything to main branch
6. Documentation is version-controlled and traceable

🎯 Run Locally:

npm run docs:generate  # Generate all documentation
npm run docs:api       # Generate API docs only
npm run docs:index     # Generate index page

🔒 ISMS Compliance:

• Documentation-as-code follows Hack23 ISMS Secure Development Policy §3.2
• All releases include complete documentation evidence
• Documentation committed to repository for full auditability

Setting Up Labels

First-time setup requires running the label creation workflow:

1. Go to Actions → Setup Repository Labels
2. Click Run workflow
3. Wait for completion
4. Labels will be automatically applied to future PRs

Configuration

Language Presets

• en - English only
• eu-core - English, German, French, Spanish, Dutch
• nordic - English, Swedish, Danish, Norwegian, Finnish
• all - All 14 supported languages

Article Types

• week-ahead - Preview of upcoming parliamentary events
• committee-reports - Committee activity analysis (coming soon)
• propositions - Legislative proposals analysis (coming soon)
• motions - Parliamentary motions analysis (coming soon)
• breaking - Breaking news coverage (coming soon)

Contributing

We welcome contributions from developers, journalists, translators, and security researchers!

How to Contribute

Please read our comprehensive Contributing Guide for:

• Development workflow and setup instructions
• Code quality requirements and testing standards
• Pull request process and review guidelines
• Security best practices and ISMS compliance
• Multi-language contribution guidelines

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to conduct@hack23.com.

Security

If you discover a security vulnerability, please follow our Security Policy for responsible disclosure. Do not report security issues through public GitHub issues.

Contributors

See AUTHORS.md for a list of contributors who have helped make this project possible. Contributions are welcome! Please see CONTRIBUTING.md for detailed guidelines on:

• Code quality requirements (ESLint, Prettier, JSDoc)
• Testing requirements (80% line coverage, 75% branch coverage)
• Security requirements (input validation, XSS prevention, dependency scanning)
• Commit message format (conventional commits)
• Pull request process

Security-Critical Contributions: All security-related changes must align with SECURITY_ARCHITECTURE.md and Hack23 ISMS Secure Development Policy.

Security Policy

For security vulnerability reporting and disclosure process, please see SECURITY.md.

Responsible Disclosure:

• Report vulnerabilities privately via GitHub Security Advisories
• 48-hour acknowledgment, 7-day validation, 30-day remediation for critical issues
• Public recognition for security researchers (unless anonymity requested)

Badge Maintenance

Maintaining Security Badge Status

EU Parliament Monitor maintains security excellence through continuous compliance with OpenSSF best practices:

OpenSSF Scorecard (Target: ≥7.0)

Current Optimizations:

• ✅ Branch protection on main branch
• ✅ Required code review for pull requests
• ✅ SHA-pinned GitHub Actions
• ✅ CodeQL SAST enabled
• ✅ Dependabot alerts enabled
• ✅ SECURITY.md present
• ✅ No dangerous workflow patterns

Monitoring: View current score at OpenSSF Scorecard Dashboard

CII Best Practices (Target: Passing → Silver → Gold)

Requirements Met:

• ✅ Public version control (GitHub)
• ✅ Public issue tracker (GitHub Issues)
• ✅ LICENSE file (Apache-2.0)
• ✅ CONTRIBUTING.md with clear guidelines
• ✅ CODE_OF_CONDUCT.md
• ✅ SECURITY.md with vulnerability reporting
• ✅ Documentation in README
• ✅ Automated testing (Vitest + Playwright, ≥80% coverage)
• ✅ Static analysis (CodeQL, ESLint)
• ✅ Dependency scanning (Dependabot, npm audit)

Registration: Complete questionnaire at CII Best Practices

SLSA Level 3 (Status: ✅ Implemented)

Provenance Generation:

• ✅ Automated on releases via .github/workflows/release.yml
• ✅ Build attestations using actions/attest-build-provenance@v2
• ✅ SBOM generation using SPDX format
• ✅ Artifacts uploaded to GitHub Releases

Verification: View attestations at https://github.com/Hack23/euparliamentmonitor/attestations/

FOSSA License Compliance

Setup Required:

1. Sign up at FOSSA
2. Connect GitHub repository
3. Configure license policy (Apache-2.0 compatible only)

Badge: Updates automatically after scan completion

REUSE Compliance (Status: ✅ Implemented)

Compliance Verification:

• ✅ .reuse/dep5 covers all files without headers
• ✅ Apache-2.0 license applied to all project files
• ✅ Copyright notices: "2024-2026 Hack23 AB"

Workflow: Runs on push, pull requests, and weekly via .github/workflows/reuse.yml

ISMS Policy References

This project adheres to Hack23 ISMS policies:

Policy	Relevance	Implementation
Open Source Policy	Security badge requirements, governance artifacts	All badges, docs, REUSE compliance
CRA Conformity Assessment Process	EU Cyber Resilience Act compliance	CRA-ASSESSMENT.md
Secure Development Policy	Development security standards	SECURITY_ARCHITECTURE.md, SAST/SCA/DAST
Threat Modeling Policy	Threat analysis requirements	STRIDE analysis in THREAT_MODEL.md
Vulnerability Management	Remediation SLAs	SECURITY.md disclosure timeline
Classification Framework	Data classification	Public/Medium/Medium (L1/L2/L2)
Incident Response Plan	Security incident procedures	Linked in SECURITY.md

Compliance Frameworks

EU Parliament Monitor aligns with multiple compliance frameworks:

Framework	Controls	Evidence
ISO 27001	A.12.6.1 (Vulnerability Management), A.14.2.8 (Security Testing)	CodeQL, Dependabot, npm audit
NIST CSF 2.0	Identify, Protect, Detect, Respond, Recover	SECURITY_ARCHITECTURE.md compliance matrix
CIS Controls v8.1	18.3 (Remediate Vulnerabilities), 2.7 (Allowlisting)	Automated scanning, SBOM
GDPR	Data Protection by Design	European Parliament open data (public)
NIS2	Article 20, 21 (Cybersecurity Risk Management)	Threat model, security controls
EU Cyber Resilience Act	SBOM, Vulnerability Disclosure, Annex I/V	CRA-ASSESSMENT.md, SLSA provenance, SECURITY.md

🤖 AI-Disrupted News Generation & Agentic Intelligence

"While traditional newsrooms debate whether AI will replace journalists, EU Parliament Monitor quietly deployed 8 autonomous AI agents that generate investigative political intelligence in 14 languages before most reporters have finished their morning coffee. The future of parliamentary journalism didn't send a memo — it opened a pull request."

The EU Parliament Monitor doesn't just report on European Parliament activity — it autonomously generates deep political intelligence at machine speed, with editorial quality that would make legacy news desks nervous. Every article is researched, written, localized, and prepared for publication by AI agents that operate by default on live European Parliament data via the MCP Server (46 tools, real-time data), with transparent fallback to placeholder/test data when live access is unavailable as described above. The agents automatically generate content and open publication-ready pull requests; publication to the site occurs when a human reviews and merges those PRs.

📰 Agentic News Generation Architecture

8 autonomous news workflows run on precision schedules, each powered by a dedicated GitHub Copilot agentic workflow that fetches live EP data (with documented fallback behavior), generates Economist-style analysis, and opens publication-ready pull requests across all 14 languages:

graph LR
    subgraph "📅 Daily Cycle (Mon-Fri)"
        CR["🏛️ Committee Reports<br/>04:00 UTC"]
        PR["📜 Propositions<br/>05:00 UTC"]
        MO["⚖️ Motions<br/>06:00 UTC"]
    end

    subgraph "📆 Weekly Cycle"
        WA["📋 Week Ahead<br/>Fri 07:00 UTC"]
        WR["📊 Weekly Review<br/>Sat 09:00 UTC"]
    end

    subgraph "📅 Monthly Cycle"
        MA["🔭 Month Ahead<br/>1st 08:00 UTC"]
        MR["📈 Monthly Review<br/>28th 10:00 UTC"]
    end

    subgraph "🎛️ On-Demand"
        AG["🚀 Article Generator<br/>Manual Dispatch"]
    end

    MCP["🔌 EP MCP Server<br/>46 Tools · Live Data"]

    MCP --> CR & PR & MO & WA & WR & MA & MR & AG

    style CR fill:#1a5276,color:#fff
    style PR fill:#1a5276,color:#fff
    style MO fill:#1a5276,color:#fff
    style WA fill:#117a65,color:#fff
    style WR fill:#117a65,color:#fff
    style MA fill:#7d3c98,color:#fff
    style MR fill:#7d3c98,color:#fff
    style AG fill:#b9770e,color:#fff
    style MCP fill:#c0392b,color:#fff

Loading

Workflow	Schedule	Focus	Output
🏛️ Committee Reports	Mon–Fri 04:00 UTC	Committee decisions & activities	14 language articles
📜 Propositions	Mon–Fri 05:00 UTC	Legislative proposals analysis	14 language articles
⚖️ Motions	Mon–Fri 06:00 UTC	Motions & resolutions analysis	14 language articles
📋 Week Ahead	Fridays 07:00 UTC	Upcoming parliamentary preview	14 language articles
📊 Weekly Review	Saturdays 09:00 UTC	Past week retrospective	14 language articles
🔭 Month Ahead	1st of month 08:00 UTC	Strategic monthly outlook	14 language articles
📈 Monthly Review	28th of month 10:00 UTC	Monthly retrospective analysis	14 language articles
🚀 Article Generator	Manual dispatch	Multi-type article generation	Configurable

🧠 The Intelligence Stack

The platform combines 8 core news-pipeline AI agents (from a catalog of 22+ specialized agents), 39+ TypeScript source modules, 21 CI/CD workflows, and 46 MCP data tools into a fully autonomous political intelligence pipeline:

graph TB
    subgraph "🤖 8 Core News Pipeline Agents"
        A1["📰 News Journalist<br/><i>Economist-style reporting</i>"]
        A2["🔄 Data Pipeline<br/><i>MCP integration</i>"]
        A3["🎨 Frontend<br/><i>WCAG 2.1 AA</i>"]
        A4["✅ Quality Engineer<br/><i>Testing & validation</i>"]
        A5["🔒 Security Architect<br/><i>ISMS compliance</i>"]
        A6["📚 Documentation<br/><i>C4 & architecture</i>"]
        A7["⚙️ DevOps Engineer<br/><i>CI/CD automation</i>"]
        A8["📋 Product Task<br/><i>Issue management</i>"]
    end

    subgraph "⚙️ 21 CI/CD Workflows"
        W1["8 News Generation"]
        W2["5 Security & Compliance"]
        W3["2 Testing"]
        W4["2 Release & Deploy"]
        W5["4 Automation & Infra"]
    end

    subgraph "📊 Data Layer"
        MCP["🔌 EP MCP Server<br/>46 Tools"]
        TS["📦 39+ TypeScript Modules"]
        L14["🌍 14 Languages"]
    end

    A1 --> W1
    A2 --> MCP
    A7 --> W2 & W3 & W4
    W1 --> TS --> L14

    style A1 fill:#2e86c1,color:#fff
    style A2 fill:#2e86c1,color:#fff
    style A3 fill:#2e86c1,color:#fff
    style A4 fill:#2e86c1,color:#fff
    style A5 fill:#2e86c1,color:#fff
    style A6 fill:#2e86c1,color:#fff
    style A7 fill:#2e86c1,color:#fff
    style A8 fill:#2e86c1,color:#fff
    style W1 fill:#1a5276,color:#fff
    style W2 fill:#7d3c98,color:#fff
    style W3 fill:#117a65,color:#fff
    style W4 fill:#b9770e,color:#fff
    style MCP fill:#c0392b,color:#fff
    style TS fill:#1c2833,color:#fff
    style L14 fill:#117a65,color:#fff

Loading

🚀 Future Advance: AI Evolution Roadmap (2026–2037)

"We're not just keeping up with AI — we're building the editorial infrastructure for the era when machines understand parliamentary procedure better than most MEPs."

The platform evolves through six phases from agentic news generation to AGI-enhanced transformative democracy. Full details in Future Mindmap and Future Workflows.

timeline
    title EU Parliament Monitor — AI Evolution Roadmap
    section Phase 1 (2026)
        Agentic News : 8 autonomous workflows
                     : 14-language generation
                     : MCP data integration
                     : Economist-style analysis
    section Phase 2 (2027)
        Predictive Analytics : Voting outcome prediction
                             : Legislative impact forecasting
                             : Cross-party coalition detection
                             : Automated trend analysis
    section Phase 3 (2028–2029)
        Multi-Modal Intelligence : Video plenary analysis
                                 : Real-time debate tracking
                                 : Infographic auto-generation
                                 : Autonomous content pipelines
    section Phase 4 (2030–2031)
        Near-Expert Analysis : 50+ parliament coverage
                             : Expert-level policy briefs
                             : Predictive governance models
                             : Universal language support
    section Phase 5 (2032–2033)
        Global Coverage : 100+ parliaments
                        : Pre-AGI capabilities
                        : Real-time policy impact
                        : Cross-jurisdiction analysis
    section Phase 6 (2034–2037)
        AGI Era : Transformative democracy
               : 195 national legislatures
               : Policy prediction before proposal
               : Human oversight maintained

Loading

🤖 Phase 6: AGI Era & Transformative Democracy (2034–2037)

When AGI or near-AGI systems become available, the platform architecture is designed to scale responsibly:

Capability	Description
🤖 Autonomous Analysis	AGI-powered real-time political intelligence across all 195 national legislatures
🌐 Universal Language Support	Every UN language supported natively — no translation pipeline, native generation
📊 Predictive Governance	Policy impact prediction before legislation is proposed — anticipatory intelligence
⚖️ Ethical AI Governance	Human oversight maintained regardless of AI capability level — democratic safeguards hardcoded
🛡️ Democratic Safeguards	Platform architecture prevents weaponization or manipulation — transparency by design

📈 AI Model Evolution Strategy

Assumptions: Major AI model upgrades annually, competitors (OpenAI, Google, Meta, EU sovereign AI) evaluated at each release. Architecture accommodates potential paradigm shifts (quantum AI, neuromorphic computing).

Projected workflow counts below include all CI/CD workflow definitions, agentic workflow sources, and planned variants across the platform. The 2026 baseline (~44) builds on the current 21 deployed .yml workflows + 8 agentic .md sources (29 today) plus planned security, localization, and data-pipeline additions.

Year	Projected Workflow Definitions	AI Model	Key Capability
2026	44–50	Opus 4.7–4.9	🟢 Agentic news generation
2027	50–55	Opus 5.x	🔵 Predictive analytics
2028	55–65	Opus 6.x	🟣 Multi-modal content
2029	65–75	Opus 7.x	🟠 Autonomous pipeline
2030	75–85	Opus 8.x	🔴 Near-expert analysis
2031–2033	85–100	Opus 9–10.x / Pre-AGI	⚪ Global coverage
2034–2037	100–120+	AGI / Post-AGI	⭐ Transformative platform

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#1a5276', 'primaryTextColor': '#fff', 'lineColor': '#2e86c1', 'secondaryColor': '#117a65'}}}%%
xychart-beta
    title "Projected Workflow Definitions & Variants (2026–2037)"
    x-axis ["2026", "2027", "2028", "2029", "2030", "2031", "2032", "2033", "2034", "2035", "2036", "2037"]
    y-axis "Workflow definitions & variants" 0 --> 130
    bar [44, 53, 60, 70, 80, 88, 94, 100, 105, 110, 115, 120]
    line [44, 53, 60, 70, 80, 88, 94, 100, 105, 110, 115, 120]

Loading

📚 Detailed Roadmap Documentation

Document	Focus	Coverage
📘 Future Mindmap	Capability evolution & system vision	2026–2037 AI/ML roadmap, multi-parliament expansion, API ecosystem
📗 Future Workflows	CI/CD evolution & automation roadmap	Security hardening, performance optimization, AGI-ready pipelines

License

Copyright 2024-2026 Hack23 AB

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See LICENSE file for full details.

Credits

This project is based on the news generation implementation from Hack23/riksdagsmonitor.

Author

Hack23 AB - Intelligence Operations Team