Skip to content

WORKFLOWS.md

Latest commit

 

History

History
2629 lines (2056 loc) · 155 KB

WORKFLOWS.md

File metadata and controls

2629 lines (2056 loc) · 155 KB
Raw

Hack23 Logo

🔄 EU Parliament Monitor — CI/CD Workflows

🛡️ Automated Security Excellence Through Continuous Integration
🎯 Transparent Pipeline Operations Demonstrating ISMS Policy Compliance

Owner Version Effective Date Review Cycle

📋 Document Owner: CEO | 📄 Version: 4.6 | 📅 Last Updated: 2026-05-28 (UTC) | 📦 Release: v0.9.26
🔄 Review Cycle: Quarterly | ⏰ Next Review: 2026-08-28

📊 Workflow Status Badges

CI/CD Pipeline Status:

Test and Report Knip — Unused Code Detection CodeQL E2E Tests Release Dependency Review Scorecard supply-chain security Deploy S3 REUSE Compliance

Security & Quality Metrics:

OpenSSF Scorecard SLSA 3

🔐 ISMS Policy Alignment

EU Parliament Monitor's CI/CD workflows implement security controls mandated by Hack23 AB's ISMS framework:

ISMS Policy Workflow Implementation
🛠️ Secure Development Policy SAST (CodeQL), SCA (Dependency Review), E2E (Playwright), performance testing
📝 Change Management Automated testing gates, security scanning, PR review requirements
🔍 Vulnerability Management Dependabot, CodeQL, OSSF Scorecard, npm audit, security advisories
🔓 Open Source Policy SLSA attestations, SBOM generation, REUSE license compliance
🔐 Information Security Policy Security-hardened runners, SHA-pinned actions, least privilege permissions
🔑 Access Control Policy OIDC authentication, minimal workflow permissions, branch protection
🔒 Cryptography Policy Sigstore signing, SLSA L3 provenance, build attestations
🚨 Incident Response Plan Automated rollback procedures, incident classification workflows
💾 Backup & Recovery Policy Multi-CDN deployment (S3 + GitHub Pages DR), version control
🤝 Third Party Management SHA-pinned actions, dependency review, supply chain security

Compliance Framework Mapping

Framework Version Relevant Controls Implementation
ISO 27001 2022 A.8.25, A.8.26, A.8.27, A.8.28, A.12.1.4, A.12.6.1, A.14.2.1 Secure development lifecycle, testing, change management
NIST CSF 2.0 PR.DS, DE.CM, ID.SC, RS.MI Data security, monitoring, supply chain, mitigation
CIS Controls v8.1 2.2, 4.1, 7.1, 16.1, 17.1 Software inventory, access control, code signing, application security
EU CRA 2024 Art. 10, Art. 11 SBOM generation, vulnerability disclosure, security updates

📚 Architecture Documentation Map

Document Focus Description Documentation Link
Architecture 🏛️ Architecture C4 model showing current system structure View Source
Future Architecture 🏛️ Architecture C4 model showing future system structure View Source
Mindmaps 🧠 Concept Current system component relationships View Source
Future Mindmaps 🧠 Concept Future capability evolution View Source
SWOT Analysis 💼 Business Current strategic assessment View Source
Future SWOT Analysis 💼 Business Future strategic opportunities View Source
Data Model 📊 Data Current data structures and relationships View Source
Future Data Model 📊 Data Enhanced European Parliament data architecture View Source
Flowcharts 🔄 Process Current data processing workflows View Source
Future Flowcharts 🔄 Process Enhanced AI-driven workflows View Source
State Diagrams 🔄 Behavior Current system state transitions View Source
Future State Diagrams 🔄 Behavior Enhanced adaptive state transitions View Source
Security Architecture 🛡️ Security Current security implementation View Source
Future Security Architecture 🛡️ Security Security enhancement roadmap View Source
Threat Model 🎯 Security Political Threat Landscape analysis View Source
Classification 🏷️ Governance CIA classification & BCP View Source
CRA Assessment 🛡️ Compliance Cyber Resilience Act View Source
Workflows ⚙️ DevOps CI/CD documentation View Source
Future Workflows 🚀 DevOps Planned CI/CD enhancements View Source
Business Continuity Plan 🔄 Resilience Recovery planning View Source
Financial Security Plan 💰 Financial Cost & security analysis View Source
End-of-Life Strategy 📦 Lifecycle Technology EOL planning View Source
Unit Test Plan 🧪 Testing Unit testing strategy View Source
E2E Test Plan 🔍 Testing End-to-end testing View Source
Performance Testing ⚡ Performance Performance benchmarks View Source
Security Policy 🔒 Security Vulnerability reporting & security policy View Source

📋 Executive Summary

EU Parliament Monitor employs a comprehensive suite of GitHub Actions workflows (~15 standard + 15 agentic — 14 unified news-<type>.md + news-translate.md) for automated intelligence operations, quality assurance, security scanning, and release management. All workflows follow the Hack23 ISMS Secure Development Policy standards.

Workflow Portfolio

# Workflow Purpose Schedule / Trigger ISMS Alignment
1 Agentic News Workflows (×15) AI-generated multi-language news articles (14 article-type unified news-<type>.md + news-translate) Varied schedules (see §1) Integrity controls (Medium)
2 Test & Report Unit + integration tests, 5,933+ tests, coverage, performance On PR/push to main Quality assurance (ISO 27001 A.12.1.4)
3 CodeQL SAST security scanning (JS/TS + GitHub Actions) On PR/push + weekly Saturday Vulnerability management (ISO 27001 A.12.6)
4 E2E Tests End-to-end Playwright tests (Chromium) + axe-core On PR/push + daily midnight UTC Functional validation + WCAG 2.1 AA
5 Release Build, attest (SLSA L3), document, publish to npm (provenance) Manual/tag push SLSA L3, Documentation-as-code, npm provenance
6 Dependency Review Supply chain security scanning On PR Supply chain security (NIST CSF ID.SC)
7 OpenSSF Scorecard Security posture assessment Weekly Tuesday 07:20 UTC Continuous improvement
8 Deploy S3 Production deployment to AWS S3 + CloudFront (OIDC, egress: block) Push to main Infrastructure as Code
9 REUSE Compliance License and copyright verification (REUSE 3.3) On PR/push + weekly Monday Open Source Policy
10 SLSA Provenance Build provenance attestation (integrated in release.yml) On release + manual Supply chain security (SLSA L3)
11 Compile Agentic Workflows Compile .md → .lock.yml via gh-aw CLI (pinned GH_AW_VERSION: v0.77.3) Manual dispatch Automation governance
12 Agentics Maintenance Housekeeping for agentic workflows (stale lock cleanup, health probes) Scheduled Automation governance
13 Labeler Automatic PR labeling On pull_request_target Workflow governance
14 Setup Labels Repository label management Manual dispatch Repository governance
15 Copilot Setup Steps GitHub Copilot agent environment setup Push/PR to itself + manual Agent infrastructure
16 news-translate-reconciler Reconcile missing translation artifacts across 14 languages Scheduled Translation consistency
17 MCP Reliability Probe Daily EP/IMF/WB MCP health matrix via npm run mcp:probe Daily + manual Third-party data source assurance

🔒 Security Posture: All 14 standard workflows use SHA-pinned actions (100%), Harden Runner (step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0), and minimal permissions following least privilege principle. Agentic workflows implement the gh-aw 3-layer defense-in-depth trust model: 🔒 Substrate (AWF Squid firewall, Docker isolation, MCP sandboxing), 📋 Configuration (lock-file compilation, SHA pinning, actionlint/zizmor/poutine scanners, content sanitization, integrity filtering), and 📐 Plan (SafeOutputs permission isolation, Threat Detection pipeline, Secret Redaction, JSONL audit trail).

🏗️ Pipeline Architecture

graph LR
    A[Code Push] --> B[Build & Test]
    B --> C[SCA Scan]
    C --> D[CodeQL Scan]
    D --> E[Quality Gate]
    E --> F[Security Gate]
    F --> G[SBOM Generation]
    G --> H[Attestations]
    H --> I[Release]
    I --> J[Deploy]

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:1.5px,color:white
    classDef process fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef security fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white
    classDef decision fill:#f39c12,stroke:#e67e22,stroke-width:1.5px,color:black
    classDef success fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white

    class A trigger
    class B process
    class C,D security
    class E,F decision
    class G,H security
    class I,J success
Loading

Workflow Relationships

flowchart TB
    subgraph "Continuous Integration"
        direction TB
        PR[Pull Request] --> CodeQLScan[CodeQL Analysis]
        PR --> DependencyReview[Dependency Review]
        PR --> Labeler[PR Labeler]
        PR --> REUSECheck[REUSE Compliance]
        CodeQLScan --> SecurityEvents[Security Events]
    end

    subgraph "Agentic Content Pipeline"
        direction TB
        Schedule1[Scheduled / Manual Triggers] --> AgenticNews[15 Agentic News Workflows]
        AgenticNews --> Analysis[Political Intelligence Analysis]
        Analysis --> Articles[14-Language Article Generation]
        Articles --> ContentPR[Content Pull Request]
    end

    subgraph "Continuous Deployment"
        direction TB
        Release[Release Trigger] --> BuildTest[Prepare & Test]
        BuildTest --> BuildPackage[Build & Package]
        BuildPackage --> GenerateSBOM[Generate SBOM]
        GenerateSBOM --> Attestations[Create Attestations]
        Attestations --> CreateRelease[Create GitHub Release]
    end

    subgraph "Security Scanning"
        direction TB
        Weekly[Weekly Schedule] --> WeeklyScan[CodeQL Weekly Scan]
        BranchProtection[Branch Protection] --> Scorecard[Scorecard Analysis]
    end

    PR -.-> |"approved & merged"| main[Main Branch]
    ContentPR -.-> |"reviewed & merged"| main
    main --> Scorecard
    main --> DeployS3[Deploy to S3 + CloudFront]
    main -.-> |"tag created"| Release

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:1.5px,color:white
    classDef process fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef success fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white
    classDef decision fill:#f39c12,stroke:#e67e22,stroke-width:1.5px,color:black
    classDef security fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white

    class PR,CodeQLScan,DependencyReview,Labeler,REUSECheck trigger
    class Release,BuildTest,BuildPackage,GenerateSBOM,Attestations,CreateRelease process
    class main,DeployS3 success
    class Schedule1,AgenticNews,Analysis,Articles,ContentPR decision
    class SecurityEvents,Weekly,WeeklyScan,BranchProtection,Scorecard security
Loading

🚀 Workflow Detailed Documentation

1. Agentic News Workflows (×15)

🎯 Purpose: AI-powered generation of multi-language news articles about European Parliament activities using GitHub Copilot. The 14 unified news-<type>.md article workflows run on the claude-opus-4.8 model; the news-translate.md translation helper runs on claude-sonnet-4.6. 📁 Architecture: 15 markdown source files (14 unified news-<type>.md covering 14 article types + 1 news-translate.md helper) compiled to 15 .lock.yml files via gh aw compile (GitHub Agentic Workflows CLI) 🌐 Languages: 14 (en, sv, da, no, fi, de, fr, es, nl, ar, he, ja, ko, zh) 📜 Horizon registry: Every horizon's data window, cadence, mandatory artifacts, stage budgets, scenario depth and electoral overlay is defined in src/config/article-horizons.ts — the single source of truth consumed by the aggregator, the forward-statements registry, and the drift-guard tests.

Agentic Workflow Schedule Matrix

🤖 Workflow 📄 File 📅 Schedule ⏱️ Timeout
🚨 EU Parliament Breaking News news-breaking.lock.yml Every 6 hours (0 */6 * * *) 60 min
🔮 EU Parliament Week Ahead news-week-ahead.lock.yml Friday 07:00 UTC 60 min
📊 EU Parliament Month Ahead news-month-ahead.lock.yml 1st of month 08:00 UTC 60 min
🌐 EU Parliament Quarter Ahead news-quarter-ahead.lock.yml 1st of month 08:00 UTC (0 8 1 * *) 60 min
🛰️ EU Parliament Year Ahead news-year-ahead.lock.yml Quarterly — 2nd of Jan/Apr/Jul/Oct 08:00 UTC (0 8 2 1,4,7,10 *) 60 min
🗓️ EU Parliament Term Outlook news-term-outlook.lock.yml Semi-annual — 1 Jan & 1 Jul 08:00 UTC (0 8 1 1,7 *) 60 min
🗳️ EU Parliament Election Cycle news-election-cycle.lock.yml Annual — 1 Dec 08:00 UTC (0 8 1 12 *) + T-180 / T-90 / T-30 imminent triggers 60 min
📋 EU Parliament Week in Review news-week-in-review.lock.yml Saturday 09:00 UTC 60 min
📈 EU Parliament Month in Review news-month-in-review.lock.yml 28th of month 10:00 UTC 60 min
📚 EU Parliament Quarter in Review news-quarter-in-review.lock.yml 5th of month 08:00 UTC (0 8 5 * *) 60 min
📜 EU Parliament Year in Review news-year-in-review.lock.yml Annual — 15 Jan 08:00 UTC (0 8 15 1 *) 60 min
🗳️ EU Parliament Plenary Votes & Resolutions news-motions.lock.yml Weekdays (Mon–Fri) 06:00 UTC 60 min
⚖️ EU Parliament Legislative Procedures news-propositions.lock.yml Weekdays (Mon–Fri) 05:00 UTC 60 min
🏛️ EU Parliament Committee Activity news-committee-reports.lock.yml Weekdays (Mon–Fri) 04:00 UTC 60 min
🌐 Translate Articles news-translate.lock.yml Manual dispatch only (workflow_dispatch) 60 min

Each news-<type>.md workflow runs Stages A → B → C → D → E in one 60-minute session and produces exactly one PR containing both analysis artifacts and rendered article HTML. The earlier split-pair news-<type>-analysis.md + news-<type>-article.md layout and the manual news-article-generator.md helper were deleted in the April-2026 aggregator-pipeline migration. The news-translate.md helper (manual dispatch only) is the sole exemption from the single-PR rule.

Long-horizon family classification

Family Slugs Stage budgets (A/B/C/D/E) Stage-C exit PR-call deadline Electoral overlay
Standard short-form breaking, week-ahead, month-ahead, week-in-review, month-in-review, committee-reports, motions, propositions 5/22/4/2/2 = 35 (prospective) · 4/22/4/2/2 = 34 (retrospective) minute 36 ≤ 45 —
Long-horizon prospective quarter-ahead, year-ahead 5/24–25/4/2/2 minute 38–39 ≤ 45 —
Long-horizon retrospective quarter-in-review, year-in-review 4–5/24–25/4/2/2 minute 38–39 ≤ 45 —
Electoral overlay term-outlook, election-cycle 5/26–28/4/2/2 = up to 41 minute 42 ≤ 47 ✅

Electoral-overlay invariants (enforced by Stage-C completeness gate when electoralOverlay: true in the registry):

  1. The mandatory artifact set includes forward-projection.md, term-arc.md, seat-projection.md, mandate-fulfilment-scorecard.md, presidency-trio-context.md, commission-wp-alignment.md, forward-indicators.md, comparative-international.md, and historical-parallels.md.
  2. The scenario-forecast must include an EP-election outcome branch.
  3. forwardStatementsHorizonDays is bounded at 1500 (term-outlook) / 1825 (election-cycle) — the registry caps it at 1825.
  4. dataWindow.anchor is next-election (constant June 2029 today), giving deterministic windowing across runs.

Fallback behaviour: every horizon inherits the standard fallback chain — empty today MCP feed → fall back to the wider sliding window declared in the registry; failed get_voting_records for retrospective runs → EP Open Data Portal direct fetch (see scripts/mcp-setup.sh and src/mcp/ep-mcp-client.ts). A failed long-horizon run does not fall back to a shorter horizon — Stage-C blocks the PR and the workflow exits non-zero.

Agentic Workflow Architecture

All 15 agentic workflows share a common architecture. The 14 article workflows render the committed analysis run into all 14 language-aware HTML variants in Stage D; news-translate.md is a manual helper for refreshing translated Markdown sources when needed:

graph TD
    A[🕐 Schedule / Manual Trigger] --> B[🔑 Activation Job]
    B --> C{Conditions Met?}
    C -->|✅ Yes| D[🤖 Agent Job<br/>GitHub Copilot + claude-opus-4.8<br/>translate: claude-sonnet-4.6]
    C -->|❌ No| E[⏭️ Skip]
    D --> F[📥 Checkout Repository]
    F --> G[⚙️ Setup Node.js 26]
    G --> H[📦 Install Dependencies]
    H --> I[🔗 Install EP MCP Server v1.3.20+]
    I --> J1[🔬 Analysis Stage<br/>Political Intelligence Pipeline<br/>--analysis flag]
    J1 --> J1a[📊 Classification: significance, impact-matrix, actors, forces]
    J1 --> J1b[🛡️ Threat Assessment: Political Threat Landscape,<br/>actor-threats, disruption]
    J1 --> J1c[📈 Risk Scoring: risk-matrix, SWOT, velocity, capital-at-risk]
    J1a --> J1d["📁 analysis/daily/YYYY-MM-DD/article-type/"]
    J1b --> J1d
    J1c --> J1d
    J1d --> J[📰 Generate News Articles<br/>npx tsx src/generators/news-enhanced.ts --analysis]
    J --> K[🇬🇧 English HTML Output]
    K --> L[📝 Create Pull Request<br/>Includes analysis/ artifacts]
    L --> M[✅ PR Ready for Review]
    L -.-> N[🌐 news-translate Workflow<br/>Generates 13 Additional Languages]

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef process fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef decision fill:#f39c12,stroke:#e67e22,stroke-width:2px,color:black
    classDef skip fill:#95a5a6,stroke:#7f8c8d,stroke-width:1.5px,color:white
    classDef analysis fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white
    classDef output fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white

    class A,B trigger
    class D,F,G,H,I process
    class C decision
    class E skip
    class J1,J1a,J1b,J1c,J1d analysis
    class J,K,L,M,N output
Loading

Bounded Context Architecture (TypeScript Modules)

The workflow support logic is organized into bounded contexts under src/workflows/:

src/workflows/
├── index.ts                    # Barrel export — public API
├── types.ts                    # Shared contracts: DataMode, GateVerdict, PipelineStage
├── completeness-gate/          # Stage C analysis validation
│   ├── index.ts                # Public API
│   ├── types.ts                # ValidationRules, ValidatorOptions, ValidationContext
│   ├── constants.ts            # Regex patterns, thresholds (extracted from validator JS)
│   └── validators.ts           # Pure validation functions (hasMermaid, hasWepBand, etc.)
├── infrastructure/             # Shell safety validation rules and utilities
│   ├── index.ts                # Public API
│   └── shell-safety.ts         # SHELL_SAFETY_RULES[], validateShellSafety()
└── safe-outputs/               # Stage E PR creation constraints
    ├── index.ts                # Public API
    └── types.ts                # SafeOutputsPRParams, FORBIDDEN_PHRASES, timing constraints

Design principles:

  • Single responsibility per module — each file has one clear purpose
  • Strict TypeScript typing — all interfaces use readonly fields
  • Pure functions — validators are side-effect-free and independently testable
  • Constants extracted — regex patterns defined once, used by both validator scripts and tests
  • Barrel exports — each bounded context has an index.ts for clean imports

Import pattern:

import { completenessGate, infrastructure, safeOutputs } from './workflows/index.js';
// or selectively:
import { hasPlaceholders, computeEffectiveMinLines } from './workflows/completeness-gate/index.js';

Common Agentic Workflow Properties

Property Value
Source format Markdown (.md) compiled by gh aw compile
Lock format YAML (.lock.yml) — auto-generated, do not edit directly
AI Model claude-opus-4.8 (14 article workflows) / claude-sonnet-4.6 (news-translate.md) via GitHub Copilot CLI
Top-level permissions {} (empty — no default permissions)
Activation job permissions contents: read
Agent job permissions contents: write, pull-requests: write, issues: write, models: read
Concurrency group gh-aw-${{ github.workflow }}
Node.js version 26
EP MCP Server european-parliament-mcp-server@1.3.20 (globally installed via scripts/mcp-setup.sh, MCP gateway EP_MCP_GATEWAY_URL resolved dynamically from MCP config; default http://host.docker.internal:8080/mcp/european-parliament)
Data sources European Parliament MCP Server v1.3.20+ (primary, 60+ tools — sliding + fixed-window feeds + analytical), IMF REST SDMX 3.0 (native fetch in src/mcp/imf-mcp-client.ts, primary economic source — WEO+FM+IFS+BOP+ER+PCPS+GFSR+EREO+FSI+GFS+DOT), World Bank Open Data MCP (non-economic only — WDI social/health/education/environment/governance). Economic-context enforcement is editorial at the Stage-C completeness review against .github/prompts/03-analysis-completeness-gate.md and the per-artifact line floors in analysis/methodologies/reference-quality-thresholds.json — the runtime articlePolicyHas* gates were purged in April-2026
Analysis stage Stage B writes structured Markdown artifacts under the run directory using the 10-step AI-driven analysis protocol
Analysis output analysis/daily/{date}/{article-type}/ (or suffixed same-day variants) containing manifest.json, raw data, Stage-B artifacts, article.md, and article-meta.json. Article-type scoping prevents merge conflicts between concurrent workflows.

5-Stage Pipeline (matches the prompt library 00→09)

Every article-generating news-*.md (all except news-translate.md) executes the same five bounded stages. This is the canonical flow; it aligns 1-to-1 with the ten-file prompt library in .github/prompts/:

Stage Name Prompt file(s) Output location
A Data collection 01-data-collection.md + 07-mcp-reference.md analysis/daily/<YYYY-MM-DD>/<type>-run<NN>/intelligence/*
B Analysis (2-pass mandatory) 02-analysis-protocol.md → analysis/methodologies/ai-driven-analysis-guide.md (10 steps, Rules 1–22) classification / threat / risk / synthesis artifacts under the same run dir
C Completeness gate 03-analysis-completeness-gate.md → npm run validate-analysis vs analysis/methodologies/reference-quality-thresholds.json blocks PR if any floor is missed
D Deterministic article render 04-article-generation.md + 05-analysis-to-article-contract.md; no AI-authored HTML analysis/daily/<date>/<type>/article.md, article-meta.json, news/<slug>.en.md, and 14 news/<slug>-<lang>.html files
E Single PR 06-pr-and-safe-outputs.md → one safeoutputs___create_pull_request call at end of run GitHub PR (max 1 per run; news-translate.md is the sole exemption — multi-call flush for 14-language fan-out)

Stage D's Read-Before-Write rule requires the agent to consult every artifact produced in Stage B before drafting prose; the artifact → article-section map lives in 04-article-generation.md § 7.1. The 39-template artifact catalogue (14 agentic-workflow templates — which include 6 reusable framework templates — plus 25 per-artifact templates, and the analysis-index.md + README.md catalogue files) is enumerated in analysis/templates/README.md and mapped to methodologies in analysis/methodologies/artifact-catalog.md.

Imports structure (shared component + runtime-import + lock-file)

Each news-*.md (except news-translate.md) uses gh-aw's imports: field twice:

imports:
  - shared/mcp/news-mcp-servers.md        # frontmatter-only: MCP servers merged into frontmatter
  - ../agents/news-generation.agent.md    # body-only: Required Reading + Stage Contract appended to prompt
  • shared/mcp/news-mcp-servers.md is the single source of truth for the mcp-servers: block (EP, World Bank, IMF, MCP Gateway mounts). Editing it propagates to every importing workflow on next compile.
  • .github/agents/news-generation.agent.md contributes body-only content (confirmed against gh-aw v0.77.3, 2026-05-28: imported agent frontmatter is not merged into workflow frontmatter). It appends the canonical Required Reading order and the 5-stage Stage Contract to every importing prompt.
  • Both files are tracked; any change triggers a recompile of every importing .lock.yml by compile-agentic-workflows.yml.

safeoutputs semantics (gh-aw v0.77.3)

Every news-*.md declares:

safe-outputs:
  create-pull-request:
    max: 1                # default for every news-*.md

Documented exceptions:

  • news-translate.md uses excluded-files: and a multi-call flush pattern with max-patch-size; it is exempt from the single-PR rule and is the only workflow that calls safeoutputs___create_pull_request more than once.

Critical semantic: safeoutputs___create_pull_request takes a synchronous git format-patch snapshot AT CALL TIME of the agent's working tree. Calling it before all files are written produces a partial PR. It must therefore be invoked exactly once at the very end of the run, after every article, analysis artifact, and manifest has been written to disk. The banned alternatives — checkpoint PRs, keep-alive heartbeats, progressive safe outputs, and safeoutputs___push_repo_memory — are CI-lint-enforced by scripts/lint-prompts.js / npm run lint:prompts. See .github/prompts/README.md § Drift-guard Lint for the full rule set.

Compilation Process

Source markdown files are compiled to lock files using the GitHub Agentic Workflows CLI:

# Compile all agentic workflow definitions
gh aw compile

The compile-agentic-workflows.yml workflow automates this process (see §11).

🔒 Security Controls (gh-aw Architecture)

See §1b "gh-aw Security Architecture" below for the full 3-layer trust model, SafeOutputs isolation, and Threat Detection pipeline.

Control Implementation ISMS Reference
🔐 Input Validation MCP data validated via TypeScript schemas before use ISO 27001 A.14.2.1
🧹 HTML Sanitization Strip scripts, encode entities in generated content OWASP Top 10 (XSS)
🔒 Empty Top-Level Permissions permissions: {} — no default permissions Least privilege
🎯 Scoped Job Permissions Write permissions only on safe-output jobs (not agent) Least privilege
🔄 Concurrency Control gh-aw-${{ github.workflow }} — single concurrent run Resource governance
📝 PR-Based Output SafeOutputs subsystem buffers writes, threat-detects, then PRs Change review
🌐 Network Isolation AWF Squid proxy enforces domain allowlist (default-deny) Network Security Policy
🔍 Compilation Security actionlint + zizmor + poutine scanners validate .lock.yml NIST CSF PR.AC-4
🔑 Secret Redaction Unconditional artifact scan before upload (if: always()) Cryptography Policy

ISMS Evidence

Unique Data & Analytics Per Workflow (PRIO 1)

Every workflow downloads unique data and produces article-type-specific analytics. The following matrix shows the mandatory MCP data downloads and analytical tools unique to each workflow:

flowchart LR
    subgraph "🔴 Breaking News"
        B1["adopted_texts_feed\nevents_feed\nprocedures_feed\nmeps_feed"] --> B2["detect_voting_anomalies\nanalyze_coalition_dynamics\nearly_warning_system\ngenerate_political_landscape"]
    end

    subgraph "📋 Motions"
        M1["adopted_texts_feed\nquestions_feed\nmeps_feed\nprocedures_feed"] --> M2["detect_voting_anomalies\nanalyze_coalition_dynamics\nget_voting_records\ncompare_political_groups"]
    end

    subgraph "📜 Propositions"
        P1["procedures_feed\ndocuments_feed\nadopted_texts_feed\nplenary_docs_feed"] --> P2["search_documents\nmonitor_legislative_pipeline\ntrack_legislation\nanalyze_legislative_effectiveness"]
    end

    subgraph "🏛️ Committee Reports"
        C1["committee_docs_feed\nplenary_docs_feed\nadopted_texts_feed\nprocedures_feed"] --> C2["get_committee_info\nmonitor_legislative_pipeline\nanalyze_legislative_effectiveness"]
    end

    style B1 fill:#dc3545,stroke:#b02a37,color:#fff
    style B2 fill:#dc3545,stroke:#b02a37,color:#fff
    style M1 fill:#fd7e14,stroke:#ca6510,color:#fff
    style M2 fill:#fd7e14,stroke:#ca6510,color:#fff
    style P1 fill:#ffc107,stroke:#cc9a06,color:#000
    style P2 fill:#ffc107,stroke:#cc9a06,color:#000
    style C1 fill:#198754,stroke:#146c43,color:#fff
    style C2 fill:#198754,stroke:#146c43,color:#fff
Loading
Workflow Mandatory Feed Data Mandatory Analytical Tools Unique Focus
Breaking adopted_texts, events, procedures, meps (today→one-week) + documents, plenary_docs, committee_docs, questions detect_voting_anomalies, analyze_coalition_dynamics, early_warning_system, generate_political_landscape ⚡ Only TODAY's items; 6-hour cycle
Motions adopted_texts, parliamentary_questions, meps, procedures detect_voting_anomalies, analyze_coalition_dynamics, get_voting_records, compare_political_groups 🗳️ Per-resolution vote breakdowns
Propositions procedures, documents, adopted_texts, plenary_documents search_documents, monitor_legislative_pipeline, track_legislation, analyze_legislative_effectiveness 📜 Procedure stage tracking
Committee committee_documents, plenary_documents, adopted_texts, procedures get_committee_info, monitor_legislative_pipeline, analyze_legislative_effectiveness 🏛️ Per-committee deep analysis
Week Ahead events, procedures, plenary_documents, plenary_session_documents get_plenary_sessions (future), get_committee_info, monitor_legislative_pipeline, generate_political_landscape 📅 Prospective agenda analysis
Weekly Review adopted_texts, procedures, plenary_documents, parliamentary_questions get_voting_records, detect_voting_anomalies, generate_political_landscape 📊 Retrospective outcome review
Month Ahead events, procedures, plenary/committee docs, adopted_texts, session docs, meps get_plenary_sessions, get_committee_info, monitor_pipeline, generate_landscape, compare_groups, analyze_delegation 📆 Strategic calendar outlook
Monthly Review adopted_texts, procedures, plenary_documents, parliamentary_questions get_voting_records, detect_anomalies, generate_landscape, compare_groups, analyze_effectiveness 📈 Comprehensive monthly trends
Translate — (manual helper) — 🌐 Refresh translated Markdown sources

PRIO 1 MANDATE: Each workflow ALWAYS downloads its mandatory feed data and runs its mandatory analytical tools BEFORE deciding whether to produce an article. Data collection is NEVER skipped, even for noop runs.

1b. Agentic News Workflows (gh-aw)

📄 Files: .github/workflows/news-*.md (14 content workflows + 1 translation workflow) 🎯 Purpose: AI-powered news article generation using GitHub Agentic Workflows (gh-aw) with European Parliament MCP Server data ⏰ Schedule: Various (see table below)

Architecture: Unified Article Render + Manual Translation Helper

The agentic news system uses a deterministic aggregator architecture:

  1. Article workflows (14 workflows) → Collect data, author Stage-B artifacts, run Stage-C completeness checks, and render all 14 language-aware HTML variants from the committed analysis run.
  2. Translation helper (1 workflow) → Manual-only workflow for refreshing translated Markdown sources with multi-call safe-output flushes when needed.

This keeps political-intelligence authoring in Markdown artifacts and makes HTML generation reproducible across every language.

graph TD
    A[📋 Article Workflows<br/>Stage A-E] -->|Write| B[🧠 analysis/daily run]
    B -->|Render| C[🌐 14 HTML variants]
    C -->|Single safe-output| D[📝 Content PR]
    B -.->|Manual refresh| E[🌐 news-translate.md]
    E -.->|Translated Markdown sources| C
    D -->|Merge + deploy| F[☁️ S3 / CloudFront<br/>Language Switchers + Sitemaps]

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef process fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef render fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white
    classDef translation fill:#e67e22,stroke:#d35400,stroke-width:1.5px,color:white

    class A trigger
    class B,D process
    class C,F render
    class E translation
Loading

Content Workflow Schedule

Workflow Article Type Schedule Focus
🤖 Workflow 🏷️ Type 📅 Schedule 🎯 Purpose
--- --- --- ---
news-committee-reports.md committee-reports Mon–Fri 04:00 UTC Committee activity analysis
news-propositions.md propositions Mon–Fri 05:00 UTC Legislative pipeline tracking
news-motions.md motions Mon–Fri 06:00 UTC Voting patterns & resolutions
news-week-ahead.md week-ahead Fri 07:00 UTC Upcoming parliamentary agenda
news-month-ahead.md month-ahead 1st of month 08:00 UTC Monthly strategic outlook
news-week-in-review.md week-in-review Sat 09:00 UTC Week in review
news-month-in-review.md month-in-review 28th of month 10:00 UTC Monthly retrospective
news-breaking.md breaking Every 6 hours Real-time EP feed events

Each news-<type>.md runs the full Stage A→E protocol in one ~60-minute session and produces exactly one PR with both analysis artifacts and the rendered article HTML. The earlier split-pair news-<type>-analysis.md + news-<type>-article.md layout and the manual news-article-generator.md helper were deleted in the April-2026 aggregator-pipeline migration (the prior legacy single-job news-<type>.md were briefly replaced by split pairs in 2025 because those exceeded the safeoutputs MCP TTL — the unified workflows intentionally do not set engine.mcp.session-timeout because the bundled MCP gateway rejects the field; the default gateway keepalive is used and the PR call lands by minute ≤ 45 of the 60-min timeout-minutes cap).

Translation Workflow

Workflow Schedule Purpose
news-translate.md Manual (workflow_dispatch) only Refresh or complete sv, da, no, fi, de, fr, es, nl, ar, he, ja, ko, zh translated Markdown sources; multi-call safe-output flush is allowed only here

Supported Languages (14 total)

English (en) Swedish (sv) Danish (da) Norwegian (no) Finnish (fi)
German (de) French (fr) Spanish (es) Dutch (nl) Arabic (ar)
Hebrew (he) Japanese (ja) Korean (ko) Chinese (zh)
🌐 Always-14-Languages-Always-HTML Contract (May 2026)

Every article.md produced by an agentic workflow always renders to 14 language-aware HTML files — there is no opt-out, no subset, and no markdown-only escape hatch.

Property Before May 2026 After May 2026
npm run generate-article -- --lang en --lang sv Rendered selected languages only Rejected — flag removed; CLI always renders all 14
npm run generate-article -- --markdown-only Skipped HTML emission Rejected — flag removed; HTML is always emitted
news-translate.md languages: workflow_dispatch input (all-non-en / eu-core / nordic / comma-separated) Configurable subset Removed — every run translates to all 13 non-English languages
Article workflows (news-<type>.md) Stage D Could be configured to render fewer languages via --lang Always render all 14 languages from the committed analysis run

Why: per-language partial coverage created a long tail of articles where <slug>-en.html existed but <slug>-zh.html did not, and silent CLI subset selection let workflows drift from the committed product contract. Hard-wiring "always 14" at the CLI boundary makes coverage a property of every run rather than a property of every invocation choice. The aggregator's idempotent skip-write logic (mtime ≥ source artefacts) keeps re-renders cheap when only a subset of languages were actually missing.

Programmatic escape hatch: generateArticle() (called from unit / integration tests for speed) still accepts langs and markdownOnly directly on the options object — only the CLI surface area (and therefore every workflow) is locked down.

🔒 gh-aw Security Architecture (3-Layer Trust Model)

Reference: GitHub Agentic Workflows Architecture — official specification for AW security layers, trust boundaries, and component isolation.

All 15 agentic workflows inherit the gh-aw 3-layer defense-in-depth trust model. Each layer provides independent security guarantees — compromise of any single layer does NOT compromise the system:

Layer Boundary EU Parliament Monitor Implementation Threat Assumption
🔒 Substrate VM → kernel → container → network AWF Squid proxy (network.allowed 30+ entries across GitHub/infra, EU, IMF, World Bank, Hack23 domains), Docker --cap-drop=ALL, MCP server sandboxing, iptables default-deny Adversary controls user-level containers
📋 Configuration Declarative specs + toolchain Lock-file compilation (gh aw compile v0.77.3), SHA-pinned actions, actionlint/zizmor/poutine scanners, content sanitization, integrity filtering Misconfiguration, overly permissive specs
📐 Plan Staged execution + output vetting SafeOutputs (read-only agent → buffered → vetted PR), Threat Detection pipeline, Secret Redaction (if: always()), JSONL audit trail Incorrect plan, stage bypass attempts 
flowchart LR
    subgraph L1["🔒 Substrate (Layer 1)"]
        AWF["🌐 AWF Firewall<br/>Squid Proxy<br/>Default-Deny Egress"]
        DOCKER["🐳 Container Isolation<br/>cap-drop=ALL<br/>Resource Limits"]
        MCP_S["📦 MCP Sandboxing<br/>Per-Server Container<br/>Tool Allowlists"]
    end

    subgraph L2["📋 Configuration (Layer 2)"]
        COMPILE["🔐 Lock-File Compilation<br/>Schema + SHA Pin"]
        SCANNERS["🔍 Security Scanners<br/>actionlint + zizmor + poutine"]
        SANITIZE["🧹 Content Sanitization<br/>@mention + URI + Unicode"]
        INTEGRITY["🛡️ Integrity Filtering<br/>Author Trust Levels"]
    end

    subgraph L3["📐 Plan (Layer 3)"]
        SAFE["✅ SafeOutputs<br/>Read-Only Agent<br/>Buffered Writes"]
        THREAT["🧠 Threat Detection<br/>AI + Custom Analysis"]
        REDACT["🔑 Secret Redaction<br/>Unconditional Scan"]
        AUDIT["📋 JSONL Audit Trail<br/>90-Day Retention"]
    end

    L1 --> L2 --> L3

    style AWF fill:#ffe1e1,stroke:#c0392b
    style DOCKER fill:#ffe1e1,stroke:#c0392b
    style MCP_S fill:#ffe1e1,stroke:#c0392b
    style COMPILE fill:#e1f5ff,stroke:#2980b9
    style SCANNERS fill:#e1f5ff,stroke:#2980b9
    style SANITIZE fill:#e1f5ff,stroke:#2980b9
    style INTEGRITY fill:#e1f5ff,stroke:#2980b9
    style SAFE fill:#e8f5e9,stroke:#1e8449
    style THREAT fill:#e8f5e9,stroke:#1e8449
    style REDACT fill:#e8f5e9,stroke:#1e8449
    style AUDIT fill:#e8f5e9,stroke:#1e8449
Loading
🌐 AWF Network Firewall (Substrate Layer)
Endpoint Group Purpose Access Pattern
GitHub + base runtime (defaults, github, node, docker.io) Workflow orchestration, actions, dependency/runtime access HTTPS
EU data domains (*.europa.eu, ec.europa.eu, eur-lex.europa.eu, data.ecb.europa.eu, etc.) EP/institutional legislative and policy data HTTPS
IMF domains (*.imf.org, including api.imf.org) IMF SDMX 3.0 and IMF data services HTTPS (API key where required)
World Bank domains (*.worldbank.org) World Bank MCP and economic context datasets HTTPS
Hack23/platform domains (*.hack23.com, *.euparliamentmonitor.com, related project domains) Project-controlled APIs and platform integrations HTTPS
host.docker.internal:8080 MCP Gateway (Docker bridge, local-only) HTTP (local bridge)
Authoritative source Full allowlist maintained in .github/workflows/shared/config/news-common-settings.md Version-controlled
❌ All non-allowlisted domains Blocked by AWF default-deny policy iptables DROP
🛡️ SafeOutputs Permission Isolation (Plan Layer)
Agent Job (read-only) → Buffered Artifacts → Threat Detection (separate job) → Safe Output Jobs (write)
  • Agent never has direct contents: write at runtime — writes are buffered as artifacts
  • Separate Threat Detection job downloads artifacts and performs AI + custom security analysis
  • Only on "safe" verdict do Safe Output Jobs execute with scoped write permissions
  • Single PR per workflow run enforced by safe-outputs: create-pull-request: max: 1
🧹 Content Sanitization (Configuration Layer)
Mechanism Protection
🏷️ @mention → `@mention` Prevents unintended GitHub notifications
🤖 fixes #123 → `fixes #123` Prevents automatic issue linking/closure
🔒 <script> → (script) Blocks XML/HTML injection vectors
🌐 http://evil.com → (redacted) URI filtering (HTTPS + trusted domains only)
📏 0.5 MB / 65k lines max Truncation prevents resource exhaustion
🔤 Homoglyph normalization Prevents visual spoofing attacks
📊 Security Controls Summary
Control Implementation ISMS Reference
🌐 Network Isolation AWF Squid proxy with network.allowed 30+ domain entries (see news-common-settings.md), iptables default-deny Network Security Policy
🐳 Container Isolation Docker --cap-drop=ALL, resource limits, read-only FS ISO 27001 A.8.31
📦 MCP Sandboxing Per-server Docker containers, tool allowlisting Secure Development Policy
🔐 Compilation Security Schema validation, expression safety, SHA pinning ISO 27001 A.8.25
🔍 Security Scanners actionlint + zizmor + poutine at compile time NIST CSF PR.AC-4
🧹 Input Sanitization @mention neutralization, URI filtering, content limits OWASP Top 10 (XSS/Injection)
🛡️ Integrity Filtering Author trust levels (min-integrity: approved) Data integrity
✅ SafeOutputs Permission separation — read-only agent, buffered writes Least privilege
🧠 Threat Detection AI-powered analysis of agent outputs before write ISO 27001 A.12.6
🔑 Secret Redaction Unconditional artifact scan (if: always()) Cryptography Policy
📋 Audit Trail JSONL logging, 90-day retention, gh aw logs/audit ISO 27001 A.12.4
👁️ Human Review Mandatory PR approval before merge Change management
🔄 Concurrency gh-aw-${{ github.workflow }} prevents parallel conflicts Resource governance

Enhanced Analysis Features (v2)

The following 14 unified article-generation workflows include mandatory analytical enhancements: news-breaking.md, news-week-ahead.md, news-month-ahead.md, news-quarter-ahead.md, news-year-ahead.md, news-term-outlook.md, news-election-cycle.md, news-week-in-review.md, news-month-in-review.md, news-quarter-in-review.md, news-year-in-review.md, news-committee-reports.md, news-propositions.md, news-motions.md. The news-translate.md workflow has complementary analysis-fidelity requirements for preserving these elements in translation.

🎭 Multi-Stakeholder Perspective Requirements

Every major parliamentary action must be analyzed from at least 3 of 6 stakeholder perspectives:

Perspective Analysis Focus
EP Political Groups Coalition dynamics, group influence, voting alliances
Civil Society & NGOs Citizens' rights, democratic participation, transparency
Industry & Business Regulatory burden, market effects, compliance dynamics
National Governments Subsidiarity, implementation requirements, national interests
EU Citizens Direct life impact, rights, services, democratic representation
EU Institutions Commission, Council, ECB, Court of Justice — inter-institutional dynamics

Stakeholder perspective analysis is rendered by the TypeScript generator (buildStakeholderPerspectivesSection) as a card grid in each article's deep-analysis portion. Agents provide structured perspective content — impact direction (positive/negative/neutral/mixed), severity (high/medium/low), reasoning, and evidence backed by specific EP MCP data citations — and the generator handles the HTML markup (analysis-stakeholder-perspectives / stakeholder-perspectives-grid). Agents must NOT write raw HTML for this section. Impact and severity values must remain as canonical English enum tokens (e.g. positive, high) even in non-English articles — the generator handles localized display labels and CSS classing from these tokens. (Note: the separate winners/losers outcomes list uses analysis-stakeholders / stakeholder-list — that is a different section rendered by buildStakeholderSection.)

🔄 Iterative AI Content Refinement Cycle

All analytical content sections follow a mandatory 4-pass refinement process:

Pass Activity Output
Pass 1 — Initial Assessment Gather MCP baseline data; identify actors, actions, outcomes Draft narrative
Pass 2 — Stakeholder Challenge Re-examine from each stakeholder angle; flag blind spots Revised draft with gaps identified
Pass 3 — Evidence Cross-Validation Verify claims against EP documents/votes; add 🟢/🟡/🔴 confidence indicators Evidenced assertions only
Pass 4 — Synthesis & Scenarios Produce balanced conclusions; provide 2–3 forward-looking scenarios with probability labels Final publishable analysis

Localization requirement: All text labels — confidence (🟢 High / 🟡 Medium / 🔴 Low), probability (likely / possible / unlikely), and significance (High / Medium / Low) — must be rendered in the article's output language while preserving the underlying 3-level scale and keeping emoji markers (🟢/🟡/🔴, ↑↓→) unchanged. Non-English articles must use the equivalent terms in the target language, not English labels.

✅ Enhanced Analysis Quality Gates

In addition to the existing content quality gates (500-word minimum, no synthetic IDs, current dates), all articles must pass two new quality gate categories:

Analysis Depth Gates:

  • Minimum 3 stakeholder perspectives analyzed per key development
  • SWOT dimensions cover both political AND economic/regulatory aspects
  • Dashboard trend indicators included (↑↓→), not just current values
  • Cross-domain policy links shown (e.g., environment ↔ trade ↔ social)
  • Evidence chains cite specific document IDs, vote counts, or MCP data points
  • Outlook provides at least 2 named scenarios with probability labels

Political Intelligence Gates:

  • Coalition dynamics named explicitly (not just "EPP and S&D voted together")
  • Each group's position explained with reasoning (incentives, ideology, constituency)
  • Winner/loser analysis identified with supporting evidence
  • Historical EP context referenced where comparable precedents exist
📄 EP Document Analysis Framework

Every key EP document featured in the deep-analysis section must include structured analysis (other document references may remain as citations without full framework analysis):

  1. Political Context — Why introduced? Who pushed it? What problem does it solve?
  2. Stakeholder Impact — Who benefits/faces costs? Quantified where possible.
  3. Procedure Stage — Where in the legislative pipeline? Next steps and timeline.
  4. Coalition Dynamics — Which groups support/oppose? Key fault lines.
  5. Significance Rating — High / Medium / Low with one-sentence justification. (Note: significance ratings use text labels, not color indicators, to avoid confusion with the 🟢/🟡/🔴 confidence scale used in the refinement cycle.)
🔬 Workflow-Specific Intelligence Modules

Each scheduled content workflow includes a tailored intelligence module beyond the shared framework:

Workflow Module Focus
news-week-ahead.md 🔭 Strategic Preview Analysis What to watch, coalitions under stress, legislative inflection points, geopolitical triggers
news-month-ahead.md 📈 Long-Term Trend Context Term trajectory, policy momentum, coalition evolution, EU external context
news-quarter-ahead.md 🧭 Quarterly Outlook Coalition stability projection, policy momentum, blocking coalitions
news-year-ahead.md 🔮 Annual Forward Projection Multi-quarter trajectory, electoral pressure, partisan/coalition shifts
news-term-outlook.md 🏛️ Term-Length Strategic Outlook Multi-year coalition viability, mandate-fulfillment trajectory
news-election-cycle.md 🗳️ Electoral-Cycle Intelligence Cycle-position drivers, group-volatility forecast
news-breaking.md ⚡ Rapid Stakeholder Impact Assessment Immediate winners/losers, market/policy signals, next 24–48 hour tracking
news-committee-reports.md 🏛️ Committee Power Dynamics Analysis Rapporteur influence, shadow rapporteur positions, amendment landscape, trilogue implications
news-propositions.md 🗓️ Legislative Pipeline Intelligence Passage probability, amendment expectations, timeline forecast, blocking coalitions
news-motions.md 🗳️ Voting Pattern Intelligence Coalition map, abstention analysis, cross-party defections, margin analysis
news-week-in-review.md 📊 Week-in-Context Analysis Parliamentary landscape shift, promises vs. delivery, surprise developments
news-month-in-review.md 🗺️ Monthly Trend Synthesis Legislative productivity, coalition stability index, policy trajectory, emerging themes
news-quarter-in-review.md 📚 Quarterly Retrospective Coalition stability index, productivity benchmarks
news-year-in-review.md 📆 Annual Retrospective Year-long trend confirmation, accountability ledger

The translation workflow has its own fidelity module:

Workflow Module Focus
news-translate.md 🌐 Analysis Fidelity Requirements Stakeholder framing preservation, confidence indicator translation, EP official terminology

📄 File: .github/workflows/test-and-report.yml
🎯 Purpose: Comprehensive testing with unit tests, integration tests, coverage reporting, and performance benchmarks
⏰ Trigger: On push to main, on PR to main
📊 Status: Test and Report

Test Coverage

Test Type Framework Coverage Target Current Status
Unit Tests Vitest 4.1.7 (happy-dom) 153 test files ✅ 5,933+ passing
Integration Tests Vitest + MCP contract suites (test/integration/mcp-integration.test.js, test/integration/mcp/imf-mcp.test.js, test/integration/mcp/worldbank-mcp.test.js) IMF/WB canonical tool lists asserted via drift-guard tests; EP MCP covered by mcp-integration.test.js (no canonical EP_MCP_TOOLS export yet) ✅ All passing
Line Coverage Vitest (V8) ≥80% ✅ 82%+
Branch Coverage Vitest (V8) ≥75% ✅ 83%+
Function Coverage Vitest (V8) ≥80% ✅ 89%+
E2E Playwright 1.60.0 + @axe-core/playwright 4.11.3 WCAG 2.1 AA ✅ Passing

Workflow Jobs (6 Jobs)

graph LR
    A[Prepare] --> B[Validation]
    A --> C[Functional Tests]
    A --> D[Performance]
    A --> E[Security Check]
    B --> F[Report]
    C --> F
    D --> F
    E --> F

    classDef prepare fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef test fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white
    classDef security fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white
    classDef perf fill:#f39c12,stroke:#e67e22,stroke-width:1.5px,color:black
    classDef report fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white

    class A prepare
    class B,C test
    class D perf
    class E security
    class F report
Loading
Job Name Purpose Key Steps
prepare Prepare Environment Cache dependencies, setup Node.js 26 Checkout, npm ci, cache
validation Validate Code ESLint, Prettier, HTMLHint, npm audit Lint, format check, HTML validation
functional-tests Functional Tests Vitest unit + integration tests Run tests, coverage report
performance Performance Testing Lighthouse CI + article generation benchmarks @lhci/cli@0.15.1, performance metrics
security-check Security Check npm audit analysis Vulnerability triage, CodeQL integration
report Generate Report Aggregate results, PR comments Coverage summary, status checks

Security Controls

Control Implementation ISMS Reference
Code Quality ESLint + Prettier Code quality standards
Vulnerability Scanning npm audit ISO 27001 A.12.6.1
Coverage Thresholds 80%+ lines, 75%+ branches Quality gates
Performance Benchmarks Lighthouse CI scoring Performance validation
False Positive Handling Intelligent npm audit triage Risk acceptance process

ISMS Evidence

2b. Knip — Unused Code Detection

📄 File: .github/workflows/knip.yml
🎯 Purpose: Detect unused files, exports, dependencies, and types across src/** and the hand-written scripts in scripts/** so the codebase stays lean ahead of releases.
⏰ Trigger: On push to main, on PR to main
📊 Mode: ⚠️ Warning-only (continue-on-error: true) until the baseline stabilises across two consecutive PR cycles, then flipped to blocking.

What Knip Scans

Surface Coverage
Source files src/**/*.ts (the authoritative TypeScript tree)
Hand-written JS All scripts/**/*.js files referenced from package.json scripts are auto-discovered (e.g. scripts/copy-vendor.js, scripts/lint-prompts.js, scripts/validate-analysis-completeness.js); files only invoked from agentic-workflow .md bodies (e.g. scripts/backport-article-seo.js, scripts/aggregator/forward-statements-registry.js) are listed explicitly in knip.json entry
Test fixtures test/**/*.test.js, e2e/**/*.spec.js
Compiled scripts/** Excluded from project (it is a 1:1 build output of src/**); CLI entry points are auto-discovered via the package.json exports map
Generated artefacts analysis/**, data/**, news/**, docs/**, coverage/**, js/vendor/** — never scanned

Configuration

The full configuration lives in knip.json. Highlights:

  • Entries explicitly list every CLI / npm-script / agentic-workflow-invoked script that knip cannot otherwise reach (e.g. scripts referenced only from .github/workflows/*.md gh-aw bodies).
  • ignoreDependencies covers runtime-spawned packages (european-parliament-mcp-server — launched via npx by the MCP gateway, not imported), browser-vendored bundles (chart.js, d3, mermaid, chartjs-plugin-annotation, papaparse — copied by scripts/copy-vendor.js), and config-only tooling (jscpd, lint-staged, eslint-config-prettier, ts-api-utils).
  • Runtime-spawned tools (e.g. european-parliament-mcp-server invoked via npx by the MCP gateway, never imported as a library) are listed in ignoreDependencies so they are not flagged as unused.

Local Workflow

npm run knip            # show all unused files / exports / deps
npm run knip:production # production-only mode (skips test entries)
npm run knip:fix        # auto-remove unused exports (use with care, review diff)

Triage Categories

Finding Category Action
Unused file (a) should be wired up Open follow-up issue; do not delete
Unused export (b) used by workflow not detected Refine entry/project in knip.json (preferred) or add comment-justified ignore
Unused dependency (c) truly unused Remove from package.json, run npm install, commit lockfile
Unused type (c) truly unused Delete and update tests

Prefer fixing knip's view of the world over adding ignores. Every ignore must carry an inline $comment or a one-line rationale in the PR description.

Workflow Jobs

Job Name Purpose Key Steps
knip Knip Scan Unused-code detection Checkout → setup Node 26 → npm ci → npm run build → npm run knip → write $GITHUB_STEP_SUMMARY → upload knip-output.txt artefact (14-day retention)

The job runs npm run build first because knip resolves imports through the package.json exports map, which points at compiled scripts/**.

Security Controls

Control Implementation ISMS Reference
Hardened Runner step-security/harden-runner (audit egress) ISO 27001 A.8.16
Read-only permissions contents: read, pull-requests: read ISO 27001 A.5.15
SHA-pinned actions All third-party actions pinned by digest ISO 27001 A.8.30
Concurrency control cancel-in-progress: true per ref Resource hygiene

ISMS Evidence

3. CodeQL Security Scanning

📄 File: .github/workflows/codeql.yml
🎯 Purpose: Static Application Security Testing (SAST) for JavaScript/TypeScript and GitHub Actions
⏰ Schedule: On push to main, on PR to main, weekly Saturday 21:33 UTC
📊 Status: CodeQL

Security Analysis

Parameter Value
Languages javascript-typescript, actions
Build Mode none (interpreted languages)
Query Suite Security Extended
Analysis Type Source code + dependencies

Vulnerability Types Detected:

  • SQL Injection
  • XSS (Cross-Site Scripting)
  • Path Traversal
  • Command Injection
  • Unsafe Deserialization
  • GitHub Actions expression injection

Security Controls

Control Implementation ISMS Reference
SAST Scanning CodeQL security-extended (JS/TS + Actions) ISO 27001 A.14.2.5
Automated Analysis On every PR + push Shift-left security
SHA-Pinned Actions All actions pinned to SHA Supply chain security
Security Alerts GitHub Security tab integration Incident response

ISMS Evidence

4. E2E Testing Workflow

📄 File: .github/workflows/e2e.yml
🎯 Purpose: End-to-end testing with Playwright across browsers
⏰ Schedule: On push to main, on PR to main, daily at midnight UTC
📊 Status: E2E Tests

Test Coverage

  • Browser: Chromium (optimised for speed)
  • Timeout: 60 minutes
  • Test Categories:
    • Homepage validation
    • Accessibility (axe-core integration)
    • Responsive design
    • Multi-language support (14 languages)
  • Artifacts: Screenshots, videos, HTML reports

Security Controls

Control Implementation ISMS Reference
Accessibility Testing axe-core WCAG AA compliance Inclusive security
Visual Regression Screenshot comparison Quality assurance
Functional Validation User workflow testing Requirements validation
Daily Regression Scheduled midnight UTC Continuous validation

ISMS Evidence

5. Release Workflow

📄 File: .github/workflows/release.yml
🎯 Purpose: Comprehensive release automation with attestations and documentation
⏰ Trigger: Manual dispatch (with version input) or tag push (v*)
📊 Status: Release

Release Pipeline

graph TD
    A[🚀 Trigger: Manual/Tag] --> B[📋 Prepare Job]
    B --> C[✅ Run Tests with Coverage]
    C --> D[🎭 Run E2E Tests]
    D --> E[📖 Generate API Docs]
    E --> F[📊 Generate Coverage Reports]
    F --> G[🎨 Generate Doc Index]
    G --> H[✅ Verify Structure]
    H --> I[💾 Commit Documentation]
    I --> J[🔨 Build Job]
    J --> K[📦 Create Release Artifacts]
    K --> L[🔐 Generate SBOM]
    L --> M[📜 Build Provenance]
    M --> N[🔏 SBOM Attestation]
    N --> O[🚀 Release Job]
    O --> P[📝 Draft Release Notes]
    P --> Q[🎉 Create GitHub Release]

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef test fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white
    classDef docs fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef build fill:#f39c12,stroke:#e67e22,stroke-width:1.5px,color:black
    classDef security fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white
    classDef release fill:#2ecc71,stroke:#27ae60,stroke-width:2px,color:white

    class A trigger
    class B,C,D test
    class E,F,G,H,I docs
    class J,K build
    class L,M,N security
    class O,P,Q release
Loading

Release Jobs

Job Name Key Permissions
prepare Prepare Release contents: write
build Build Release Package contents: read, id-token: write, attestations: write
release Create Release contents: write, id-token: write

Documentation as Code

Every release automatically generates:

Documentation Generator Output
API Documentation JSDoc 52 files, searchable
Test Coverage Vitest HTML Interactive reports
E2E Test Reports Playwright Screenshots, videos
Documentation Index Custom script Beautiful hub page

Security Controls

Control Implementation ISMS Reference
SLSA Level 3 Build provenance attestation + npm provenance (--provenance flag on publish) Supply chain security
SBOM Generation SPDX JSON format via anchore/sbom-action NTIA SBOM minimum elements
Artifact Signing GitHub Attestations API (Sigstore, OIDC keyless) Integrity verification
npm Registry Published to registry.npmjs.org/euparliamentmonitor with Sigstore provenance Supply chain transparency
Documentation Audit Trail Committed to main branch Evidence trail
Test Validation 5,933+ unit/integration tests + E2E Playwright Quality gates

ISMS Evidence

6. Dependency Review Workflow

📄 File: .github/workflows/dependency-review.yml
🎯 Purpose: Supply chain security scanning for pull requests
⏰ Trigger: On pull request
📊 Status: Dependency review enabled

Security Controls

Control Implementation ISMS Reference
License Compliance Allowed licenses only Legal compliance
Vulnerability Detection Known CVEs blocked ISO 27001 A.12.6.1
Supply Chain Security Dependency graph analysis NIST CSF ID.SC

ISMS Evidence

7. OpenSSF Scorecard Workflow

📄 File: .github/workflows/scorecards.yml
🎯 Purpose: Security posture assessment against OpenSSF best practices
⏰ Schedule: Weekly on Tuesday 07:20 UTC, push to main, branch protection rule
📊 Status: OpenSSF Scorecard

Assessed Security Practices

  • Binary artifacts
  • Branch protection
  • CI tests
  • Code review
  • Dangerous workflows
  • Dependency update tool
  • Fuzzing
  • License
  • Maintained
  • Pinned dependencies
  • SAST
  • Security policy
  • Signed releases
  • Token permissions
  • Vulnerabilities

ISMS Evidence

8. Deploy S3 Workflow

📄 File: .github/workflows/deploy-s3.yml
🎯 Purpose: Production deployment to AWS S3 + CloudFront
⏰ Trigger: Push to main
📊 Status: Production deployment

Deployment Pipeline

graph LR
    A[Push to main] --> B[Checkout Code]
    B --> C[🔒 Harden Runner<br/>egress: BLOCK]
    C --> D[Configure AWS OIDC]
    D --> E[Sync to S3]
    E --> F[Invalidate CloudFront]
    F --> G[✅ Production Live]

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef security fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white
    classDef aws fill:#FF9900,stroke:#232F3E,stroke-width:1.5px,color:white
    classDef complete fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:white

    class A trigger
    class B,C security
    class D,E,F aws
    class G complete
Loading

Note: deploy-s3.yml is the only workflow using egress-policy: block (all other workflows use audit). Outbound network calls are restricted to an explicit allowlist defined in the allowed-endpoints parameter of the Harden Runner step within deploy-s3.yml.

Security Controls

Control Implementation ISMS Reference
OIDC Federation aws-actions/configure-aws-credentials with role ARN No long-lived secrets
Egress Block Mode Harden Runner blocks all non-allowlisted endpoints Network security
IAM Least Privilege Minimal S3 + CloudFront permissions AWS security best practices
HTTPS Only CloudFront SSL/TLS distribution Data in transit protection
Infrastructure as Code GitHub Actions workflow Reproducible deployments

ISMS Evidence

9. REUSE Compliance Workflow

📄 File: .github/workflows/reuse.yml
🎯 Purpose: License and copyright compliance verification using the REUSE Specification
⏰ Schedule: On push to main, on PR to main, weekly Monday 06:00 UTC
📊 Status: REUSE Compliance

License Compliance Scope

Artifact License SPDX Header Required
Source scripts (scripts/) Apache-2.0 ✅ Yes
Test files (test/, e2e/) Apache-2.0 ✅ Yes
HTML pages (index-*.html) Apache-2.0 ✅ Yes
Workflow files (.github/workflows/) Apache-2.0 ✅ Yes
Binary assets Declared in REUSE.toml Via manifest

Security Controls

Control Implementation ISMS Reference
License Verification SPDX header validation on every file Open Source Policy
Copyright Compliance Per-file copyright tracking IP management
Supply Chain Clarity Machine-readable REUSE.toml NIST CSF ID.SC-4
SHA-Pinned Action fsfe/reuse-action pinned to SHA Supply chain security

ISMS Evidence

10. SLSA Provenance (Integrated in Release Workflow)

📄 File: .github/workflows/release.yml
🎯 Purpose: Generate cryptographic build provenance for supply chain integrity verification
⏰ Trigger: On tag push (v*) + manual dispatch with version input
📊 Status: Release

Provenance Generation Pipeline

SLSA Level 3 provenance is generated as part of the release workflow build job. All attestations and SBOM are created during the build step and attached to the immutable GitHub Release in a single atomic operation.

Attestation Artifacts

Artifact Action Verification Command
Build Provenance actions/attest-build-provenance (SHA-pinned) gh attestation verify --owner Hack23 <file>
SBOM (SPDX) anchore/sbom-action + actions/attest (SHA-pinned) gh attestation verify --owner Hack23 <file>
Distribution Archive .zip with excluded dev files SHA-256 checksum
SBOM JSON SPDX format License compliance check

Security Controls

Control Implementation ISMS Reference
OIDC Keyless Signing id-token: write + GitHub Sigstore SLSA Level 3
Immutable Release immutableCreate: true — single-write release Integrity
Minimal Permissions permissions: read-all top-level Least privilege
Harden Runner egress audit on all outbound calls Network security

ISMS Evidence

11. Compile Agentic Workflows

📄 File: .github/workflows/compile-agentic-workflows.yml
🎯 Purpose: Compile agentic workflow markdown source files (.md) into executable lock files (.lock.yml) using the gh-aw CLI (pinned GH_AW_VERSION: v0.77.3)
⏰ Trigger: Manual dispatch only (workflow_dispatch)
📊 Status: Compile Agentic Workflows

Version pin contract: GH_AW_VERSION: v0.77.3 is a repository-level environment pin in compile-agentic-workflows.yml. Bumping this pin requires re-compilation of all 15 .lock.yml files, a full PR review, and successful gh aw compile --validate across the workflow set. Any .md → .lock.yml drift is detected by agentics-maintenance.yml.

Compilation Pipeline

graph LR
    A[Manual Trigger] --> B[Checkout Repository]
    B --> C["Install gh-aw CLI<br/>(pinned v0.77.3)"]
    C --> D["Run gh aw compile --validate<br/>Validates frontmatter + safe-outputs"]
    D --> E["Commit & Push<br/>.lock.yml Files"]

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef process fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef output fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white

    class A trigger
    class B,C,D process
    class E output
Loading

gh-aw Architecture Gotchas (AI-First Quality Principle)

Gotcha Impact Mitigation
Bash Tool Call Contract Every bash tool call in an agentic workflow MUST specify BOTH command and description parameters — omitting description causes silent tool-call rejection Validator in gh aw compile --validate + agent system prompt enforcement
AWF Sandbox Expansion Restrictions Dangerous shell expansions (${var@P}, chained variable assignments building command substitutions, ${!var}, eval-like constructs) are refused by the sandbox Agents must not attempt prompt-injection patterns; sandbox logs refused attempts
max-patch-size Tuning Default create-pull-request max-patch-size is 1024 KB; news-translate.md overrides to 10240 KB at top level to accommodate 14-language fan-out patches Top-level YAML frontmatter in news-translate.md sets the elevated limit
Dynamic file resolution Agents must not hallucinate filenames; use ls -t "news/${TODAY}-${TYPE}"*"-en.html" | head -1 pattern to resolve latest English source for translation Pattern documented in workflow system prompts

Security Controls

Control Implementation ISMS Reference
Manual Trigger Only workflow_dispatch — no automatic runs Change control
Version Pin GH_AW_VERSION: v0.77.3 pinned at workflow env Supply chain integrity
Token Fallback COPILOT_MCP_GITHUB_PERSONAL_ACCESS_TOKEN with GITHUB_TOKEN fallback Credential management
Write Permissions contents: write, pull-requests: write, actions: write, issues: write Least privilege for compilation

12. Pull Request Automatic Labeler

📄 File: .github/workflows/labeler.yml
🎯 Purpose: Automatically label pull requests based on file paths and content
⏰ Trigger: pull_request_target (opened, synchronize, reopened, edited)

Security Controls

Control Implementation ISMS Reference
Minimal Job Permissions contents: read, pull-requests: write, issues: read Least privilege
Target Event pull_request_target — runs on base branch code Workflow security

13. Setup Repository Labels

📄 File: .github/workflows/setup-labels.yml
🎯 Purpose: Create and manage repository labels for issue/PR governance
⏰ Trigger: Manual dispatch only (workflow_dispatch with recreate_all input)

Security Controls

Control Implementation ISMS Reference
Manual Trigger Only workflow_dispatch — deliberate action required Change control
Minimal Permissions contents: read, issues: write Least privilege

14. Copilot Setup Steps

📄 File: .github/workflows/copilot-setup-steps.yml
🎯 Purpose: Set up the development environment for GitHub Copilot coding agents
⏰ Trigger: Push/PR to copilot-setup-steps.yml file + manual dispatch

Environment Setup

Component Version / Configuration
Node.js 25
EP MCP Server european-parliament-mcp-server (global)
Playwright Browsers Installed for E2E
Virtual Display Xvfb (:99)

Security Controls

Control Implementation ISMS Reference
Broad Read Permissions Multiple read scopes for agent access Copilot agent requirement
Write Limited Only pull-requests: write, issues: write Least privilege for agents
Token Management COPILOT_MCP_GITHUB_PERSONAL_ACCESS_TOKEN Credential management

15. Agentics Maintenance

📄 File: .github/workflows/agentics-maintenance.yml
🎯 Purpose: Housekeeping for the agentic workflow fleet — detect .md ↔ .lock.yml drift, probe MCP gateway health, prune stale analysis artifacts, verify GH_AW_VERSION: v0.77.3 is in effect.
⏰ Trigger: Scheduled (weekly) + manual dispatch

Security Controls

Control Implementation
Read-only probes Health checks write no state to the repo
Drift detection Compares gh aw compile --validate output against committed .lock.yml
PR on drift Opens a PR via safe-outputs when lock drift is detected

16. News Translate Reconciler

📄 File: .github/workflows/news-translate-reconciler.yml
🎯 Purpose: Sweep news/ for English articles that are missing translations in one or more of the 13 target languages (sv, da, no, fi, de, fr, es, nl, ar, he, ja, ko, zh) and enqueue backfill runs for news-translate.md.
⏰ Trigger: Scheduled (multiple times daily) + manual dispatch

Reconciliation Logic

flowchart LR
    A[Scan news/*.html] --> B{English article exists<br/>without all 13 translations?}
    B -- Yes --> C[Enqueue news-translate<br/>with article slug + date]
    B -- No --> D[Log reconciled]
    C --> E[news-translate produces<br/>missing languages]

    classDef scan fill:#3498db,stroke:#2980b9,stroke-width:1.5px,color:white
    classDef decision fill:#f39c12,stroke:#e67e22,stroke-width:1.5px,color:black
    classDef action fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white

    class A scan
    class B decision
    class C,E action
Loading

Security Controls

Control Implementation
Scoped dispatch Only calls news-translate.md with a specific {slug,date} input — no arbitrary workflow chaining
max-patch-size coordination Translation runs use news-translate.md's top-level 10240 KB max-patch-size for fan-out
Idempotency Skips slugs already at 14/14 language coverage

🧠 AI-First Quality Principle Enforcement

The AI-First Quality Principle (.github/skills/ai-first-quality.md, non-negotiable) governs all agentic content generation. Workflow-level enforcement:

Mandatory 2-Pass Iterative Improvement

Pass Time Budget Mandatory Outputs
Pass 1 (~60%) First 60% of workflow timeout Initial narrative draft; full MCP data fetch; first stakeholder perspective pass
Pass 2 (~40%) Remaining 40% of workflow timeout Read-back of entire draft; evidence cross-validation; gap filling; scenario elaboration

Time Budget Enforcement

Workflow timeout Minimum active time (no early exit)
60-minute workflow ≥45 minutes actively engaged
120-minute workflow (article-generator) ≥90 minutes actively engaged

Quality Gates (Validator — validate-analysis-completeness)

Before PR creation, the agentic workflow MUST run:

node scripts/utils/validate-analysis-completeness.js --article-html="$(ls -t news/${TODAY}-${TYPE}*-en.html | head -1)"

which asserts:

  • ≥80 words per SWOT item
  • ≥150 words per stakeholder perspective
  • ≥60% prose ratio (non-HTML text content)
  • ≥1 Chart.js visualization embedded
  • 0 [AI_ANALYSIS_REQUIRED] sentinel markers remaining
  • Economic context present: IMF (primary economic source, mandatory for policy articles per Stage-C review) and/or World Bank (non-economic context). Enforcement is editorial at the Stage-C completeness gate against .github/prompts/03-analysis-completeness-gate.md
  • scanHtmlForFallbackLeaks() returns empty — no FALLBACK_TEMPLATE_PATTERNS in output

Reference thresholds (analysis/methodologies/reference-quality-thresholds.json):

Artifact Min words Breaking threshold
intelligence/mcp-reliability-audit.md 200 385
intelligence/reference-analysis-quality.md 140 190

Pre-Translation Validator Gate

news-translate.md runs the validator against all English source articles before fan-out to the 13 target languages. A single failing English source blocks the entire translation run, preserving translation fidelity.

Analysis-to-Article Data Contract

buildDefaultStakeholderPerspectives in src/templates/section-builders.ts emits AI_MARKER sentinels into the HTML template. Agents author the stakeholder/impact slots directly in rendered HTML — the generator emits markup shells (analysis-stakeholder-perspectives / stakeholder-perspectives-grid) and the agent fills the semantic content. Agents MUST NOT write raw HTML for this section structure but MUST author the perspective text.

📊 Workflow Metrics

Execution Statistics

Metric Target Current Status
Test Success Rate ≥95% 100% ✅ Excellent
Test Execution Time <10 min ~3 min ✅ Excellent
Release Frequency As needed Manual ✅ On-demand
Mean Time to Deploy <1 hour ~15 min ✅ Excellent
Failed Deployment Rate <5% 0% ✅ Perfect

Security Metrics

Metric Target Current Status
Critical Vulnerabilities 0 0 ✅ Secure
High Vulnerabilities 0 0 ✅ Secure
Code Coverage ≥80% lines/functions/statements, ≥75% branches Enforced by vitest config ✅ CI-gated
SHA-Pinned Actions 100% 100% ✅ Complete
OpenSSF Score ≥8.0 TBD 🔄 Monitoring

🔐 Security Hardening Practices

EU Parliament Monitor implements industry best practices for securing CI/CD pipelines, with StepSecurity hardening for all workflows:

flowchart LR
    subgraph "🛡️ Pipeline Security Hardening"
        PH[Permissions Hardening] --> LAP[Least Access Principle]
        PS[Pin SHA Versions] --> IDT[Immutable Dependencies]
        AV[Action Verification] --> TS[Trusted Sources]
        RH[Runner Hardening] --> AL[Audit Logging]
        OT[OIDC Tokens] --> EF[Ephemeral Credentials]
    end

    subgraph "🔒 Security Measures"
        AS[Asset Security] --> AC[Asset Verification]
        DS[Dependency Security] --> PD[Dependency Pinning]
        BS[Build Security] --> BA[Build Attestations]
        RS[Release Security] --> SBOM[SBOM Generation]
    end

    PH --> AS
    PS --> DS
    AV --> BS
    RH --> RS

    classDef practice fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white
    classDef measures fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white

    class PH,PS,AV,RH,OT practice
    class LAP,IDT,TS,AL,EF practice
    class AS,DS,BS,RS measures
    class AC,PD,BA,SBOM measures
Loading

Specific Hardening Measures

The project's workflows collectively implement the following security measures (applied per workflow where applicable):

  1. 🔒 Permissions Restriction: Explicit least-privilege permissions with read-all or empty {} top-level
  2. 📌 SHA Pinning: 100% of actions pinned to specific SHA hashes — zero tag references
  3. 🛡️ Runner Hardening: StepSecurity harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0 for audit logging
  4. 📄 SBOM Generation: The release workflow generates a Software Bill of Materials in SPDX format via anchore/sbom-action
  5. 🔏 Build Attestations: The release workflow creates SLSA Level 3 provenance via actions/attest-build-provenance
  6. ⏱️ Timeout Limits: Critical workflows (e.g., E2E and agentic *.lock.yml pipelines) use explicit timeout-minutes to prevent resource exhaustion; remaining workflows rely on GitHub's default job timeouts and are monitored for anomalies
  7. 🔑 OIDC Tokens: The deploy-s3 workflow uses AWS OIDC federation — no long-lived secrets
  8. 🚫 Egress Control: The deploy-s3 workflow uses harden-runner with egress-policy: block

🛡️ Workflow Security Architecture

Workflow Permissions Matrix

Every workflow declares explicit, minimal permissions following the principle of least privilege. Some workflows use top-level permissions: read-all with job-level write overrides where needed, while others define more restrictive explicit top-level scopes tailored to their tasks.

Workflow Top-Level Job-Level Overrides Secrets Used
codeql contents: read analyze: security-events: write, packages: read, actions: read None
compile-agentic-workflows contents: write, pull-requests: write, actions: write, issues: write — COPILOT_MCP_GITHUB_PERSONAL_ACCESS_TOKEN
copilot-setup-steps contents: read, actions: read, attestations: read, checks: read, issues: write, models: read, discussions: read, pages: read, pull-requests: write, security-events: read, statuses: read — COPILOT_MCP_GITHUB_PERSONAL_ACCESS_TOKEN
dependency-review contents: read — None
deploy-s3 contents: read, id-token: write, actions: write — AWS OIDC role
e2e contents: read e2e-tests: contents: read None
labeler read-all labeler: contents: read, pull-requests: write, issues: read GITHUB_TOKEN
release read-all prepare: contents: write; build: contents: read, id-token: write, attestations: write; release: contents: write, id-token: write GITHUB_TOKEN
reuse contents: read — None
scorecards read-all analysis: security-events: write, id-token: write, contents: read, actions: read, issues: read, pull-requests: read, checks: read None
setup-labels contents: read, issues: write — GITHUB_TOKEN
test-and-report read-all validation: contents: read, pull-requests: write; functional-tests: contents: read; performance: contents: read; security-check: contents: read, security-events: write; report: contents: read, pull-requests: write None
news-* (agentic ×9) {} (empty) activation: contents: read; agent: contents: write, pull-requests: write, issues: write, models: read GITHUB_TOKEN

Security Control Layers

graph TD
    subgraph Layer1["🔵 Layer 1: Developer Workstation"]
        PC[Pre-Commit Hooks<br/>gitleaks · eslint · prettier]
        LS[Lint-Staged<br/>ESLint fix · Prettier · HTMLHint]
        PC --> LS
    end

    subgraph Layer2["🟢 Layer 2: Source Control"]
        BP[Branch Protection<br/>Required status checks]
        CR[Code Review<br/>Required approvals]
        BP --> CR
    end

    subgraph Layer3["🟡 Layer 3: CI Pipeline"]
        HR[Harden Runner v2.15.1<br/>Egress policy: audit/block]
        ST[SHA-Pinned Actions 100%<br/>Supply chain integrity]
        HR --> ST
    end

    subgraph Layer4["🔴 Layer 4: Security Scanning"]
        CQL[CodeQL SAST<br/>JS/TS + Actions analysis]
        DR[Dependency Review<br/>CVE blocking on PR]
        NA[npm audit<br/>CVE check]
        CQL --> DR --> NA
    end

    subgraph Layer5["🟣 Layer 5: Build Integrity"]
        SB[SBOM Generation<br/>CycloneDX / SPDX]
        AT[Build Attestation<br/>Sigstore / SLSA L3]
        SB --> AT
    end

    subgraph Layer6["⚫ Layer 6: Deployment"]
        S3[S3 Sync<br/>Cache-optimised headers]
        CF[CloudFront Invalidation<br/>HTTPS-only CDN]
        S3 --> CF
    end

    Layer1 --> Layer2 --> Layer3 --> Layer4 --> Layer5 --> Layer6

    classDef layer1 fill:#3498db,stroke:#2980b9,stroke-width:1.5px,color:white
    classDef layer2 fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white
    classDef layer3 fill:#f1c40f,stroke:#f39c12,stroke-width:1.5px,color:black
    classDef layer4 fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white
    classDef layer5 fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef layer6 fill:#2c3e50,stroke:#1a252f,stroke-width:1.5px,color:white

    class PC,LS layer1
    class BP,CR layer2
    class HR,ST layer3
    class CQL,DR,NA layer4
    class SB,AT layer5
    class S3,CF layer6
Loading

🪝 Pre-Commit Security Controls

The project employs two complementary pre-commit enforcement mechanisms: Husky (Node.js native) and pre-commit framework.

Husky + lint-staged

Configuration: .husky/pre-commit → runs npx lint-staged

File Pattern Commands Purpose
scripts/**/*.js eslint --fix, prettier --write JS quality + formatting
*.md prettier --write Documentation formatting
*.html htmlhint HTML validation

Pre-Commit Framework

Configuration: .pre-commit-config.yaml

graph LR
    A[git commit] --> B{Husky Hook Triggered}
    B --> C[lint-staged]
    C --> D[ESLint --fix JS]
    C --> E[Prettier --write MD]
    C --> F[HTMLHint HTML]
    D --> G{All Pass?}
    E --> G
    F --> G
    G -->|✅ Pass| H[Commit Proceeds]
    G -->|❌ Fail| I[Commit Blocked]
    I --> J[Developer Fixes Issues]
    J --> A

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef decision fill:#f39c12,stroke:#e67e22,stroke-width:2px,color:black
    classDef lint fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef pass fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white
    classDef fail fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:white

    class A trigger
    class B,G decision
    class C,D,E,F lint
    class H pass
    class I,J fail
Loading
Hook Version Purpose Security Value
gitleaks v8.16.3 Secret scanning Prevent credential exposure
mirrors-eslint v8.38.0 JS linting Code quality enforcement
end-of-file-fixer pre-commit v4.4.0 File termination Consistency
trailing-whitespace pre-commit v4.4.0 Whitespace cleanup Consistency

Security Value: gitleaks scans for hardcoded secrets (API keys, tokens, passwords) before any commit reaches the remote repository, providing first-line credential leak prevention aligned with Cryptography Policy.

🏆 SLSA Level 3 Compliance

Supply-chain Levels for Software Artifacts (SLSA) Level 3 compliance is achieved through GitHub's native attestation infrastructure integrated into the release and SLSA provenance workflows.

SLSA Requirements Matrix

SLSA L3 Requirement Implementation Workflow
Source — Version controlled Git + GitHub branch protection All
Source — Verified history Protected main branch All
Build — Scripted build npm ci + reproducible steps release.yml
Build — Build service GitHub Actions managed runners All
Build — Non-falsifiable provenance GitHub Sigstore / OIDC keyless release.yml
Build — Isolated GitHub-hosted Ubuntu ubuntu-26.04 runners All
Provenance — Available .intoto.jsonl attached to release release.yml
Provenance — Authenticated OIDC id-token: write release.yml
Provenance — Service generated actions/attest-build-provenance release.yml
Provenance — Non-falsifiable Sigstore transparency log release.yml

Build Provenance Flow

graph TD
    A[Developer: git tag vX.Y.Z] --> B[GitHub Actions: release.yml triggered]
    B --> C[prepare job: run tests + generate docs]
    C --> D[build job: npm ci - hermetic install]
    D --> E[Create release-artifacts/euparliamentmonitor-vX.Y.Z.zip]
    E --> F[anchore/sbom-action: SPDX JSON SBOM]
    F --> G[actions/attest-build-provenance<br/>Subject: release zip file]
    G --> H[GitHub Sigstore: OIDC token exchange]
    H --> I[Sigstore Transparency Log Entry]
    I --> J[.intoto.jsonl bundle saved]
    J --> K[actions/attest-sbom<br/>Subject: release zip + SBOM path]
    K --> L[GitHub Release: all artifacts attached]
    L --> M[Verification: gh attestation verify --owner Hack23 file.zip]

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef build fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef security fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white
    classDef crypto fill:#f39c12,stroke:#e67e22,stroke-width:1.5px,color:black
    classDef release fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white

    class A trigger
    class B,C,D,E build
    class F,K security
    class G,H,I,J crypto
    class L,M release
Loading

Attestation Verification

End-users can verify artifact integrity using the GitHub CLI:

# Verify build provenance
gh attestation verify euparliamentmonitor-v1.0.0.zip --owner Hack23

# Verify SBOM attestation
gh attestation verify euparliamentmonitor-v1.0.0.spdx.json --owner Hack23

# Expected output: ✅ Verification successful
# Attestation bundle verified with signer's certificate

ISMS Reference: Secure Development Policy §4.4 — Supply Chain Security

🔍 Security Scanning Pipeline

Security scanning tools are integrated into the CI/CD pipeline with triggers as documented in the matrix below (e.g., push, pull request, schedule, pre-commit).

Scanning Tool Matrix

Tool Type Triggers Findings Location Blocks Merge?
CodeQL SAST Push, PR, weekly Saturday GitHub Security tab Yes (via required check)
npm audit SCA Push, PR Workflow logs Yes (new ≥ moderate, allowlist exceptions)
Dependency Review SCA PR only PR comments Yes
ESLint SAST Lint Push, PR, pre-commit Workflow logs Yes
HTMLHint Validation Push, PR, pre-commit Workflow logs Warning
REUSE Compliance Push, PR, weekly Monday Workflow logs Yes
OpenSSF Scorecard Posture Push, weekly Tuesday SARIF → Security tab Advisory
gitleaks Secret Scan Pre-commit Terminal Yes (pre-commit)

Integrated Scanning Flow

graph LR
    subgraph Triggers["⚡ Triggers"]
        PR[Pull Request]
        PS[Push to main]
        SC[Schedule Weekly]
    end

    subgraph Scanning["🔍 Security Scanning"]
        CQL[CodeQL SAST<br/>JS/TS + Actions]
        NA[npm audit<br/>CVE check]
        DR[Dependency Review<br/>CVE block on PR]
        RL[REUSE<br/>License compliance]
        SC2[OpenSSF Scorecard<br/>Posture assessment]
    end

    subgraph Output["📊 Results"]
        GH[GitHub Security<br/>Alerts Dashboard]
        PRC[PR Comments<br/>Inline feedback]
        SAR[SARIF Upload<br/>Code scanning tab]
        WL[Workflow Logs<br/>Actions tab]
    end

    PR --> CQL & NA & DR & RL
    PS --> CQL & NA & RL & SC2

    CQL --> SAR
    NA --> WL
    DR --> PRC
    RL --> WL
    SC2 --> SAR
    SAR --> GH

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef scanning fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white
    classDef output fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white

    class PR,PS,SC trigger
    class CQL,NA,DR,RL,SC2 scanning
    class GH,PRC,SAR,WL output
Loading

🚦 Deployment Security Gates

Production deployment to AWS S3 + CloudFront is protected by multiple sequential security gates that must all pass before code reaches production.

Security Gate Sequence

graph TD
    A[Developer: Push / PR] --> B{Branch Protection<br/>Rules}
    B -->|Protected branch| C[Required Status Checks]
    C --> D{CI Tests Pass?<br/>test-and-report.yml}
    D -->|✅ Pass| E{CodeQL Scan Pass?<br/>codeql.yml}
    D -->|❌ Fail| BLOCK[🚫 Merge Blocked]
    E -->|✅ Pass| F{REUSE Compliance?<br/>reuse.yml}
    E -->|❌ Fail| BLOCK
    F -->|✅ Pass| G{Code Review<br/>Approved?}
    F -->|❌ Fail| BLOCK
    G -->|✅ Approved| H[Merge to main]
    G -->|❌ Pending| BLOCK
    H --> I[Deploy to S3<br/>deploy-s3.yml triggered]
    I --> J[Harden Runner<br/>egress: BLOCK mode]
    J --> K[OIDC AWS Auth<br/>id-token: write]
    K --> L[S3 Sync<br/>Cache-optimised]
    L --> M[CloudFront Invalidation<br/>Cache flush]
    M --> N[✅ Production Live<br/>hack23.com]

    classDef trigger fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef decision fill:#f39c12,stroke:#e67e22,stroke-width:2px,color:black
    classDef pass fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white
    classDef fail fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:white
    classDef aws fill:#FF9900,stroke:#232F3E,stroke-width:1.5px,color:white
    classDef security fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white

    class A trigger
    class B,D,E,F,G decision
    class C,H,N pass
    class BLOCK fail
    class I,J,K security
    class L,M aws
Loading

AWS Deployment Security Controls

Control Implementation ISMS Reference
OIDC Federation aws-actions/configure-aws-credentials with role ARN No long-lived secrets
Minimal IAM Role GithubWorkFlowRole — S3 + CloudFront only Least privilege
Egress Block Mode Harden Runner blocks all non-allowlisted endpoints Network security
mtime Preservation Git commit times restored before sync Change detection accuracy
Cache-Optimised Sync Per-type cache headers (HTML: 1h, assets: 1y) Performance + integrity
HTTPS Enforcement CloudFront HTTPS-only distribution Data in transit protection
TLS 1.3 CloudFront + S3 expected to enforce TLS 1.3 (configured in AWS account) Cryptography Policy

⚡ Build Cache & Install Resilience

Caching Strategy

All standard GitHub Actions workflows follow a single, consistent caching convention:

Cache Mechanism Key Pattern Expiry
npm packages (~/.npm) setup-node built-in cache: 'npm' + cache-dependency-path: package-lock.json <runner-os>-node-<hash(package-lock.json)> Expires automatically when package-lock.json changes; GitHub evicts unused entries after 7 days
Playwright browsers (~/.cache/ms-playwright) actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5 <runner-os>-playwright-v2-<scope>-<hash(package-lock.json)> Key versioned (v2) — increment the version prefix (e.g., v2 → v3) to expire all existing Playwright caches and force re-download on next run

Design decisions

  • No separate actions/cache step for ~/.npm — setup-node with cache: 'npm' already uses actions/cache internally. Adding a second explicit step creates two cache entries for the same data under different keys, wastes cache quota, and introduces key drift.
  • One canonical actions/cache SHA pin (27d5ce7f… v5.0.5) used for all non-npm caches. Every workflow that needs Playwright or another tool-specific cache MUST use this exact SHA to stay consistent and auditable.
  • cache-dependency-path: package-lock.json is always set explicitly so the internal npm cache key is scoped to the exact lock-file hash (rather than a glob scan of all **/package-lock.json files).
  • Cache expiry — GitHub Actions evicts caches unused for 7 days automatically. The v2 prefix in Playwright cache keys ensures all caches created before this change are treated as stale and re-populated on next run.

Install Resilience

All external network installs are wrapped in retry loops to survive transient registry or mirror outages:

Install type Retry mechanism Timeout
npm ci 3 attempts, 15 s back-off timeout-minutes: 10
npx playwright install-deps (apt) 3 attempts, 20 s back-off timeout-minutes: 10
npx playwright install <browser> 3 attempts, 20 s back-off timeout-minutes: 20
apt-get install (copilot setup) 3 attempts, 20 s back-off timeout-minutes: 10
npm install -g <mcp-package> 3 attempts, 15 s back-off via helper function timeout-minutes: 15

Retry pattern (shell)

for attempt in 1 2 3; do
  if <install-command>; then
    echo "✅ succeeded on attempt $attempt"
    exit 0          # or break for inline steps
  fi
  echo "⚠️ failed on attempt $attempt — retrying in 15s"
  sleep 15
done
echo "❌ failed after 3 attempts"
exit 1

All install steps also set --prefer-offline for npm ci so that the warm npm cache is used in preference to the network on subsequent attempts.

Per-workflow cache summary

Workflow npm cache Playwright cache Other caches
test-and-report.yml setup-node built-in playwright-v2-chromium-* (functional-tests job) —
release.yml setup-node built-in playwright-v2-chromium-* (prepare job) —
e2e.yml setup-node built-in playwright-v2-all-* (full browser suite) —
knip.yml setup-node built-in — —
deploy-s3.yml setup-node built-in — —
compile-agentic-workflows.yml setup-node built-in — —
copilot-setup-steps.yml setup-node built-in — —
agentics-maintenance.yml (generated) — — activity-report-logs (custom key per run+repo)

🔄 Workflow Failure Handling & Rollback

Failure Classification and Response

Failure Type Detection Automated Response Manual Action
Test failure CI job exits non-zero Workflow marked failed, merge blocked Review logs, fix code, re-push
Security finding (CodeQL, new) CodeQL analysis PR comment + GitHub Security alert Assess, fix or document false positive
Security finding (npm audit, new) npm audit in test-and-report.yml Workflow failed, findings in logs only Review audit output, update deps or add to allowlist per policy
Security finding (known / accepted) Known GHSA in audit allowlist Intelligent triage passes Document in SECURITY.md and risk register
Deployment failure S3 sync / CF invalidation error Workflow failed, previous version still live Check AWS CloudWatch, re-run
Attestation failure Sigstore API / OIDC error Release blocked Retry workflow, check OIDC config
REUSE non-compliance Missing SPDX header PR blocked Add SPDX-FileCopyrightText headers
Agentic workflow failure Agent timeout or error PR not created, workflow marked failed Review agent logs, re-trigger manually

Rollback Procedure

graph TD
    A[🚨 Production Incident Detected] --> B{Incident Type}
    B -->|Content error| C[Re-run deploy-s3.yml<br/>from previous commit]
    B -->|Security breach| D[Immediate CloudFront disable]
    B -->|Dependency vuln| E[npm audit fix + re-deploy]
    C --> F[git revert + push to main]
    F --> G[Auto-deploy triggered]
    D --> H[Revoke AWS role session]
    H --> I[Investigate + patch]
    I --> J[Re-enable CloudFront]
    E --> K[PR with dep update]
    K --> L[CI gates pass]
    L --> M[Merge + auto-deploy]
    G --> N[✅ Rollback Complete]
    J --> N
    M --> N

    classDef alert fill:#e74c3c,stroke:#c0392b,stroke-width:2px,color:white
    classDef decision fill:#f39c12,stroke:#e67e22,stroke-width:2px,color:black
    classDef content fill:#3498db,stroke:#2980b9,stroke-width:1.5px,color:white
    classDef security fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef dependency fill:#e67e22,stroke:#d35400,stroke-width:1.5px,color:white
    classDef complete fill:#27ae60,stroke:#1e8449,stroke-width:2px,color:white

    class A alert
    class B decision
    class C,F,G content
    class D,H,I,J security
    class E,K,L,M dependency
    class N complete
Loading

Recovery Time Objectives

Scenario RTO Target Procedure
Broken deployment < 15 minutes Re-run deploy-s3.yml from last good commit
Content regression < 30 minutes git revert + auto-deploy pipeline
Dependency vulnerability < 4 hours npm audit fix + PR + deploy
Security incident < 1 hour CloudFront disable + incident response

ISMS Reference: BCP Plan | Incident Response

📦 Dependabot Security Configuration

Configuration: .github/dependabot.yml

Dependabot is configured with two package ecosystems, both scheduled on Monday to batch updates and reduce CI noise.

Dependabot Configuration Summary

Ecosystem Directory Schedule PR Limit Groups
npm / Weekly, Mon 06:00 UTC 10 dev-deps (minor/patch), prod-deps (minor/patch)
github-actions / Weekly, Mon 07:00 UTC Unlimited github-actions (minor/patch)

Update Grouping Strategy

graph LR
    A[Dependabot Scan] --> B{Package Type?}
    B -->|Development dep| C[Group: development-dependencies<br/>minor + patch updates]
    B -->|Production dep| D[Group: production-dependencies<br/>minor + patch updates]
    B -->|GitHub Action| E[Group: github-actions<br/>minor + patch updates]
    C --> F[Single PR: all dev dep updates]
    D --> G[Single PR: all prod dep updates]
    E --> H[Single PR: all action SHA updates]
    F --> I[CI gates validate]
    G --> I
    H --> I
    I --> J{Pass?}
    J -->|Yes| K[Auto-merge eligible]
    J -->|No| L[Manual review required]

    classDef scanner fill:#3498db,stroke:#2980b9,stroke-width:2px,color:white
    classDef decision fill:#f39c12,stroke:#e67e22,stroke-width:2px,color:black
    classDef group fill:#9b59b6,stroke:#8e44ad,stroke-width:1.5px,color:white
    classDef pr fill:#e67e22,stroke:#d35400,stroke-width:1.5px,color:white
    classDef pass fill:#27ae60,stroke:#1e8449,stroke-width:1.5px,color:white
    classDef fail fill:#e74c3c,stroke:#c0392b,stroke-width:1.5px,color:white

    class A scanner
    class B,J decision
    class C,D,E group
    class F,G,H pr
    class I,K pass
    class L fail
Loading

Commit Message Convention

Type Prefix Example
npm dep update build(deps): build(deps): bump eslint from 8.x to 9.x
npm dev dep build(deps-dev): build(deps-dev): bump vitest from 2.x to 3.x
Actions update build(deps): build(deps): bump actions/checkout from v4 to v5

Security Labels: All Dependabot PRs are labelled dependencies + javascript or github_actions for easy filtering.

📡 Workflow Monitoring & Alerting

Workflow Status Badges

All primary workflows expose real-time status badges in README.md and this document for instant visibility into pipeline health:

Workflow Badge Target
Test & Report Test and Report Green always
CodeQL CodeQL Green always
E2E Tests E2E Tests Green always
REUSE REUSE Compliance Green always
OpenSSF Scorecard OpenSSF Scorecard ≥ 8.0/10

GitHub Security Dashboard Integration

The following tools integrate with the GitHub Security Dashboard via SARIF or native mechanisms:

Tool Integration Type Destination
CodeQL SARIF via github/codeql-action/analyze GitHub Security Dashboard (code scanning alerts)
OpenSSF Scorecard SARIF via github/codeql-action/upload-sarif GitHub Security Dashboard (code scanning alerts)
Dependabot Native GitHub integration GitHub Security Dashboard (Dependabot alerts)

Alerting Channels

Event Alert Channel Severity
Critical CVE found GitHub Security Advisories P1 — Immediate
Workflow failure on main GitHub email notification P2 — Same day
Scorecard score drop Weekly scorecard badge P3 — Weekly review
Dependabot PR opened GitHub PR notification P4 — Next Monday batch

🔒 ISMS Policy Alignment Summary

Policy Coverage

ISMS Policy Workflows Implementing Controls Evidence
🛠️ Secure Development Policy All 24 workflows This document
🔐 Information Security Policy CodeQL, OpenSSF Scorecard SECURITY_ARCHITECTURE.md
🔑 Access Control Policy deploy-s3 (OIDC), release (minimal permissions) Workflow files
🔒 Cryptography Policy deploy-s3 (TLS), release (Sigstore/SLSA) Attestations
🔓 Open Source Policy REUSE compliance workflow REUSE.toml
🔍 Vulnerability Management CodeQL, npm audit, Dependency Review GitHub Security tab, PR checks
📝 Change Management Branch protection, CI gates, PR reviews Workflow gate enforcement
🚨 Incident Response Plan Rollback procedures, incident classification §Failure Handling section

Secure Development Policy Alignment

Policy Section Implementation Evidence
§3.2 Architecture Documentation Documentation-as-code in release workflow SECURITY_ARCHITECTURE.md
§3.3 Testing Requirements 5,933+ unit/integration tests, E2E tests, 82%+ coverage Test & Report Workflow
§4.1 CI/CD Security All workflows with security controls This document
§4.3 Security Scanning CodeQL, npm audit, Dependabot CodeQL Workflow
§4.4 Supply Chain Security SLSA L3, SBOM, Dependency Review, REUSE, npm provenance Release Workflow
§10.1 CI/CD Workflow Excellence 24 automated workflows, 100% SHA-pinned This document

Compliance Frameworks

Framework Version Controls Implemented Evidence Location
ISO 27001 2022 A.8.25, A.8.26, A.8.27, A.8.28, A.12.1.4, A.12.6.1, A.14.2.1 Workflow files + this document
NIST CSF 2.0 ID.SC (Supply Chain), DE.CM (Detection), PR.DS (Data Security) SECURITY_ARCHITECTURE.md
CIS Controls v8.1 2.2, 4.1, 7.1, 16.1, 16.5, 16.7, 16.12 Scorecard
SLSA L3 Build provenance, hermetic build, non-falsifiable, authenticated Attestations
OpenSSF — SHA-pinned actions (100%), Harden Runner, branch protection Scorecard Report
EU CRA 2024 SBOM generation, vulnerability disclosure, security updates Release Workflow

🔬 Political Intelligence Operations Centre

The 15 agentic news workflows collectively form a European Parliament Political Intelligence Operations Centre — a systematic, automated pipeline that transforms raw parliamentary data into multi-language political intelligence articles published daily, weekly, monthly, quarterly, annually and across the full EP-term electoral cycle.

Intelligence Collection Cycle

The following diagram shows the complete intelligence cycle from EP data collection through analysis to multi-language publication:

flowchart TD
    subgraph Collection["📡 COLLECTION<br/>(EP MCP Server v1.3.20+)"]
        direction TB
        C1["🗳️ Votes &<br/>Adopted Texts"]
        C2["📜 Legislative<br/>Procedures"]
        C3["🏛️ Committee<br/>Documents"]
        C4["🎤 Plenary<br/>Speeches"]
        C5["❓ Parliamentary<br/>Questions"]
        C6["📅 Events &<br/>Meetings"]
        C7["👤 MEP Data &<br/>Declarations"]
    end

    subgraph Analysis["🔬 ANALYSIS<br/>(Political Intelligence Pipeline)"]
        direction TB
        A1["🏷️ Classification<br/>7-dimension taxonomy"]
        A2["⚠️ Risk Assessment<br/>5×5 Likelihood × Impact"]
        A3["🎭 Threat Landscape<br/>6 political dimensions"]
        A4["💼 SWOT Analysis<br/>Evidence-based quadrants"]
        A5["📊 Significance Scoring<br/>Publication priority"]
        A6["👥 Stakeholder Impact<br/>Multi-perspective"]
    end

    subgraph Production["📰 PRODUCTION<br/>(9 Content Workflows)"]
        direction TB
        P1["⚡ Breaking News<br/>Every 6 hours"]
        P2["📋 Daily Intelligence<br/>Motions + Propositions + Committees"]
        P3["📅 Weekly Intelligence<br/>Week Ahead + Weekly Review"]
        P4["📊 Monthly Intelligence<br/>Month Ahead + Monthly Review"]
        P5["🎯 On-Demand<br/>Article Generator"]
    end

    subgraph Distribution["🌐 DISTRIBUTION<br/>(14 Languages)"]
        direction TB
        D1["🇬🇧 English<br/>(source)"]
        D2["🇸🇪🇩🇰🇳🇴🇫🇮<br/>Nordic Languages"]
        D3["🇩🇪🇫🇷🇪🇸🇳🇱<br/>Western European"]
        D4["🇸🇦🇮🇱🇯🇵🇰🇷🇨🇳<br/>Global Languages"]
    end

    Collection --> Analysis --> Production --> D1
    D1 --> |"news-translate<br/>workflow"| D2 & D3 & D4

    style Collection fill:#1565C0,stroke:#0D47A1,color:#FFFFFF
    style Analysis fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF
    style Production fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF
    style Distribution fill:#E65100,stroke:#BF360C,color:#FFFFFF
Loading

Threat Landscape Dimensions Monitored

The political intelligence pipeline monitors six threat landscape dimensions across all parliamentary activity:

mindmap
  root((🎭 Political<br/>Threat Landscape))
    🔄 Coalition Shifts
      Grand coalition stability
      Cross-party alliance formation
      Defection patterns
      Group cohesion metrics
    🔍 Transparency Deficit
      Access-to-information gaps
      Lobbying disclosure failures
      Declaration compliance
      Procedural opacity
    ⏪ Policy Reversal
      Legislative rollback risk
      Position contradiction
      Commitment abandonment
      Implementation failure
    🏛️ Institutional Pressure
      Inter-institutional friction
      Council-Parliament disputes
      Commission accountability
      Rule-of-law mechanisms
    🚧 Legislative Obstruction
      Procedure stalling
      Amendment flooding
      Committee bottlenecks
      Trilogue deadlocks
    🗳️ Democratic Erosion
      Participation decline
      Representation gaps
      Accountability weakening
      Mandate legitimacy
Loading

Workflow Cadence — Weekly Intelligence Rhythm

The 15 agentic workflows follow a carefully orchestrated schedule to ensure continuous intelligence coverage of the European Parliament across daily / weekly / monthly / quarterly / annual / term-scoped horizons.

Note: The Gantt chart below uses sample dates (week of 2026-01-05) to illustrate the recurring weekly cadence. Mermaid's gantt format requires concrete dates; the actual schedule repeats every week.

gantt
    title Weekly Agentic Workflow Cadence UTC — Sample Week
    dateFormat YYYY-MM-DD
    axisFormat %a

    section Daily Mon-Fri
    Committee Reports 04h00 UTC    :active, d1, 2026-01-05, 1d
    Propositions 05h00 UTC         :active, d2, 2026-01-05, 1d
    Motions 06h00 UTC              :active, d3, 2026-01-05, 1d
    Breaking News 4x daily         :crit, d4, 2026-01-05, 1d

    section Weekly
    Week Ahead Fri 07h00 UTC       :d5, 2026-01-09, 1d

    section Weekend
    Weekly Review Sat 09h00 UTC    :d6, 2026-01-10, 1d

    section Translation
    Translate Weekdays 3x daily    :d7, 2026-01-05, 5d
    Translate Sat 15h00 UTC        :d8, 2026-01-10, 1d

    section Monthly
    Month Ahead 1st 08h00 UTC      :d9, 2026-01-01, 1d
    Monthly Review 28th 10h00 UTC  :d10, 2026-01-28, 1d
Loading

Data Flow — EP MCP Server to Published Article

flowchart LR
    subgraph "🏛️ European Parliament"
        EP["EP Open Data Portal"]
    end

    subgraph "🔌 MCP Layer"
        MCP["EP MCP Server<br/>v1.3.20+<br/>(180s timeout;<br/>60+ tools, sliding + fixed-window feeds)"]
    end

    subgraph "🤖 Agent Layer"
        Agent["GitHub Copilot<br/>claude-opus-4.8 (articles)<br/>claude-sonnet-4.6 (translate)"]
        Analyze["Analysis Pipeline<br/>11 methodology assets<br/>39 templates"]
    end

    subgraph "📰 Output Layer"
        EN["🇬🇧 English Article"]
        Translate["Translation Agent"]
        Multi["🌐 13 Additional<br/>Languages"]
    end

    subgraph "🚀 Deployment"
        PR["Pull Request"]
        Pages["GitHub Pages"]
        S3["AWS S3 CDN"]
    end

    EP --> MCP --> Agent --> Analyze --> EN --> PR
    EN --> Translate --> Multi --> PR
    PR --> |"merge"| Pages & S3

    style EP fill:#003399,stroke:#002266,color:#FFFFFF
    style MCP fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF
    style Agent fill:#1565C0,stroke:#0D47A1,color:#FFFFFF
    style Analyze fill:#C62828,stroke:#B71C1C,color:#FFFFFF
    style EN fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF
    style Translate fill:#E65100,stroke:#BF360C,color:#FFFFFF
    style Multi fill:#F57F17,stroke:#F9A825,color:#000000
    style PR fill:#37474F,stroke:#263238,color:#FFFFFF
    style Pages fill:#00695C,stroke:#004D40,color:#FFFFFF
    style S3 fill:#FF6F00,stroke:#E65100,color:#FFFFFF
Loading

Analysis Artifact Structure

Each content workflow deposits analysis artifacts in an isolated directory. Cross-article artifacts (such as ai-daily-synthesis.md) live at the date root analysis/daily/{date}/, while per-workflow artifacts are scoped under analysis/daily/{date}/{article-type}/:

analysis/daily/2026-03-31/
├── ai-daily-synthesis.md              ← Cross-article synthesis (date root)
├── breaking/                          ← news-breaking workflow
│   ├── manifest.json
│   ├── classification/
│   ├── threat-assessment/
│   ├── risk-scoring/
│   └── data/                          ← EP MCP data for this workflow
├── committee-reports/                 ← news-committee-reports workflow
│   ├── manifest.json
│   ├── classification/
│   └── data/
├── motions/                           ← news-motions workflow
│   ├── manifest.json
│   └── data/
├── propositions/                      ← news-propositions workflow
│   ├── manifest.json
│   └── data/
└── week-ahead/                        ← news-week-ahead workflow (Fridays)
    ├── manifest.json
    └── data/

🚨 Isolation Rule: Each workflow writes ONLY to its own {article-type-slug}/ subdirectory. Cross-workflow overwrites are prohibited. The ai-*.md synthesis files at the date root aggregate across all workflows.

📖 Prompt Library Architecture

The agentic news workflows share a common prompt library under .github/prompts/. Each file maps to a specific pipeline stage and is imported by the workflow agent at runtime:

# File Pipeline Stage Purpose
0 00-scope-and-ground-rules.md All stages Foundational rules, shell-safety constraints, banned patterns, time budgets
1 01-data-collection.md Stage A MCP tool invocation patterns, feed selection, data-window logic
2 02-analysis-protocol.md Stage B 10-step AI analysis protocol (Rules 1–22), 2-pass mandatory
3 03-analysis-completeness-gate.md Stage C Completeness validator invocation, threshold enforcement
4 04-article-generation.md Stage D Artifact-to-article section map, Read-Before-Write rule
5 05-analysis-to-article-contract.md Stage D Data contract between analysis and render
6 06-pr-and-safe-outputs.md Stage E Single PR semantics, timing constraints, banned alternatives
7 07-mcp-reference.md Stage A EP MCP Server tool reference (60+ tools), IMF/World Bank guidance
8 08-infrastructure.md All stages Shell-safety long-form rules, forbidden expansion patterns
9 09-troubleshooting.md All stages Common failure modes, workarounds, timeout handling
10 10-horizon-stage-helpers.md Stage B Long-horizon-specific artifact requirements
11 11-forward-projection.md Stage B Forward-projection methodology and scenario authoring
12 12-electoral-cycle.md Stage B Electoral overlay invariants, cycle-position drivers

Drift-Guard Lint (npm run lint:prompts)

scripts/lint-prompts.js validates every .md file in .github/prompts/ and all news-*.md workflows against banned patterns:

Banned Pattern Risk if Present
checkpoint pr Partial PRs break the single-PR invariant
keep-alive Idle heartbeats waste budget without output
heartbeat Same as keep-alive
progressive safe output Partial patches violate snapshot semantics
push_repo_memory Unaudited state persistence

The lint is wired into compile-agentic-workflows.yml and fails CI on any match. news-translate.md is exempted from the multi-call check (legitimate multi-call flush for 14-language fan-out).

AWF Firewall (Squid Proxy Allowlist)

All agentic workflows execute inside a sandboxed Docker container with network access restricted by a Squid proxy (AWF Firewall). Only explicitly allowlisted domains are reachable:

Allowed Domain Purpose
data.europarl.europa.eu EP Open Data Portal (MCP Server backend)
api.github.com GitHub API (PR creation, file operations)
github.com Git operations
registry.npmjs.org npm package resolution
sdmxcentral.imf.org IMF SDMX API (economic data)
api.worldbank.org World Bank Open Data API

All other outbound network traffic is blocked by the Squid proxy. This prevents data exfiltration and restricts the agent's attack surface to known-good endpoints.

🔬 Political Intelligence Methodologies & Templates Framework

The 15 agentic news workflows produce political intelligence using a structured framework of 22 analysis methodologies and 60 analysis artifact templates. This section documents the complete political intelligence methodology stack.

Analysis Methodology Catalogue (analysis/methodologies/)

The following 22 methodology files govern how political intelligence is authored:

# Methodology File Domain Key Capabilities
1 ai-driven-analysis-guide.md Core protocol 10-step analysis protocol, Rules 1–22, Pass-2 mandatory improvement cycle
2 osint-tradecraft-standards.md Tradecraft Admiralty Code (A1–F6), WEP confidence bands, source grading, ≥10 SATs/run
3 political-threat-framework.md Threat analysis 6-dimension political threat landscape (coalition shifts, transparency deficit, policy reversal, institutional pressure, legislative obstruction, democratic erosion)
4 political-risk-methodology.md Risk assessment 5×5 likelihood × impact matrix, residual risk, risk velocity
5 political-swot-framework.md Strategic Evidence-based SWOT/TOWS, quantitative scoring, cross-domain linkage
6 political-classification-guide.md Classification 7-dimension political alignment taxonomy, significance scoring
7 electoral-cycle-methodology.md Electoral Cycle-position drivers, volatility forecast, turnout modelling
8 electoral-domain-methodology.md Electoral Domain-specific electoral analysis (seats, mandates, coalitions)
9 forward-projection-methodology.md Forecasting Multi-scenario modelling, probability bands, time-horizon calibration
10 synthesis-methodology.md Synthesis Multi-source intelligence fusion, cross-artifact correlation
11 strategic-extensions-methodology.md Long-horizon Quarter/year/term-scoped strategic analysis extensions
12 per-artifact-methodologies.md Construction rules 34 per-artifact sections — construction rules + quality signals for each template
13 analytical-supplementary-methodology.md Supplementary Cross-session intelligence, devil's advocate, wildcards
14 per-document-methodology.md Document analysis EP document deep-analysis framework (5-point structured analysis)
15 structural-metadata-methodology.md Metadata Manifest structure, artifact cataloging, cross-reference mapping
16 imf-indicator-mapping.md Economic IMF WEO/FM/IFS/BOP/ER/PCPS indicator → article-section mapping
17 worldbank-indicator-mapping.md Economic World Bank WDI social/health/education/governance indicators
18 political-style-guide.md Style Economist-quality editorial standards, prose requirements
19 political-style-guide.json Style (machine) Machine-readable style rules for automated validation
20 artifact-catalog.md Catalogue Master map: artifact → methodology + template + depth floor + Mermaid type
21 reference-quality-thresholds.json Quality floors Per-artifact line-count floors enforced by Stage-C validator (v1.4.0)
22 README.md Index Methodology library entry point

Analysis Template Catalogue (analysis/templates/)

The following 60 templates are used by Stage-B to produce structured intelligence artifacts. They are grouped by analytical domain:

Political Analysis Templates (6)

Template Purpose Key Outputs
coalition-dynamics.md Coalition formation/dissolution analysis Alliance mapping, defection patterns, cohesion metrics
coalition-mathematics.md Quantitative coalition modelling Seat arithmetic, blocking minorities, qualified majority paths
political-capital-risk.md Political capital expenditure/depletion Leadership position strength, mandate utilisation
seat-projection.md Electoral seat projection modelling Group size forecasts, majority thresholds
voter-segmentation.md Voter base analysis Demographic segments, issue salience
voting-patterns.md Roll-call vote analysis Cross-party alliances, abstention clusters, margin analysis

Threat & Risk Templates (6)

Template Purpose Key Outputs
threat-analysis.md Structured threat identification Threat actors, capabilities, intent
threat-model.md STRIDE-based political threat modelling Attack trees, mitigation mapping
political-threat-landscape.md 6-dimension threat landscape scan Dimension severity scores, trend vectors
risk-assessment.md Likelihood × Impact risk scoring Risk register, residual risk
risk-matrix.md 5×5 risk matrix visualisation Heat map, priority ranking
actor-threat-profiles.md Per-actor threat profiles Capability, intent, opportunity scores

Strategic Analysis Templates (6)

Template Purpose Key Outputs
swot-analysis.md Evidence-based SWOT quadrants ≥80 words/item, cross-domain linkage
quantitative-swot.md Scored SWOT with numeric weighting Weighted priority scores, TOWS strategies
pestle-analysis.md Political-Economic-Social-Tech-Legal-Environmental 6-dimension macro context
forces-analysis.md Porter's 5 Forces adapted for politics Competitive dynamics, barrier analysis
scenario-forecast.md Multi-scenario probability modelling 2–4 named scenarios with WEP bands
wildcards-blackswans.md Low-probability / high-impact events Early warning signals, contingency options

Intelligence Assessment Templates (6)

Template Purpose Key Outputs
intelligence-assessment.md ICD-203-style structured assessment Key judgements, confidence levels, alternatives
devils-advocate-analysis.md Challenge function for dominant hypothesis Counter-arguments, blind-spot identification
significance-classification.md Publication priority classification High/Medium/Low + justification
significance-scoring.md Multi-factor significance score Novelty, scope, impact, urgency composite
cross-session-intelligence.md Cross-run intelligence continuity Trend tracking, hypothesis evolution
synthesis-summary.md Multi-source intelligence synthesis BLUF, evidence base, confidence assessment

Legislative Analysis Templates (6)

Template Purpose Key Outputs
legislative-pipeline-forecast.md Procedure stage tracking & timeline Passage probability, next steps, blockers
legislative-velocity-risk.md Legislative pace risk assessment Acceleration/deceleration signals, backlog risk
legislative-disruption.md Amendment flooding/obstruction detection Disruption indicators, obstruction tactics
mandate-fulfilment-scorecard.md Political programme delivery tracking Promise vs. delivery, completion percentage
implementation-feasibility.md Legislative implementation assessment Transposition complexity, compliance burden
parliamentary-calendar-projection.md Session calendar forward-projection Sitting weeks, recess periods, crunch points

Context & Comparative Templates (7)

Template Purpose Key Outputs
economic-context.md IMF/World Bank economic context GDP, inflation, employment, fiscal indicators
historical-baseline.md Historical norm establishment Baseline metrics for deviation detection
historical-parallels.md Precedent-based reasoning Analogous situations, outcomes, lessons
comparative-international.md Cross-jurisdiction comparison EU vs. national parliament comparisons
presidency-trio-context.md Council Presidency trio analysis Priority alignment, legislative agenda
commission-wp-alignment.md Commission Work Programme tracking CWP delivery, legislative pipeline alignment
term-arc.md EP term trajectory analysis Term phase, momentum indicators

Forward-Looking Templates (5)

Template Purpose Key Outputs
forward-indicators.md Leading indicator identification Early warning signals, predictive metrics
forward-projection.md Structured scenario projection Time-horizon-calibrated WEP probability bands
impact-matrix.md Multi-stakeholder impact assessment Impact scores by stakeholder × dimension
consequence-trees.md Cascading consequence modelling 2nd/3rd-order effects, feedback loops
per-file-political-intelligence.md Per-document intelligence extraction Document-level political significance

Media & Stakeholder Templates (4)

Template Purpose Key Outputs
media-framing-analysis.md Media narrative frame identification Dominant frames, counter-narratives
stakeholder-impact.md Stakeholder impact assessment (≥150 words/perspective) Multi-perspective analysis, winners/losers
stakeholder-map.md Stakeholder power/interest mapping Influence quadrant, alliance networks
actor-mapping.md Political actor identification & classification Actor profiles, motivations, capabilities

Meta & Audit Templates (10)

Template Purpose Key Outputs
methodology-reflection.md Analysis quality self-assessment (Step 10.5) SAT count (≥10), WEP coverage, improvement notes
workflow-audit.md Workflow execution audit trail Stage timings, tool calls, data coverage
mcp-reliability-audit.md MCP Server reliability assessment Tool success rates, latency, data freshness
cross-reference-map.md Inter-artifact cross-reference network Artifact dependencies, citation graph
cross-run-diff.md Delta analysis between consecutive runs Changed assessments, new signals
data-download-manifest.md MCP data download record Tools invoked, data volumes, timestamps
reference-analysis-quality.md Quality benchmark comparison Per-artifact quality scores vs. reference
imf-vintage-audit.md IMF data vintage verification Dataset recency, WEO edition, vintage dates
session-baseline.md Session initial state capture Starting conditions, prior-run context
political-classification.md 7-dimension political classification output Alignment scores, taxonomy placement

Output & Index Templates (4)

Template Purpose Key Outputs
executive-brief.md BLUF executive summary Key judgements, confidence, recommendations
deep-analysis.md Extended deep-analysis section Full analytical depth, evidence chains
intelligence-assessment.md ICD-203 formatted assessment Structured intelligence product
analysis-index.md Run-level artifact index Table of contents for all run outputs

Quality Gates & Enforcement

Per-Artifact Line Floors (reference-quality-thresholds.json v1.4.0)

The Stage-C completeness validator (scripts/validate-analysis-completeness.js) enforces minimum line counts per artifact type:

Category Floor Range Enforcement
Executive brief 80–120 lines RED (blocking) — PR creation blocked
Intelligence artifacts 40–100 lines RED (blocking)
Risk scoring artifacts 35–80 lines RED (blocking)
Classification artifacts 30–60 lines RED (blocking)
Data manifests 20–40 lines RED (blocking)

DataMode reductions (when EP MCP data availability is constrained):

  • full (default): 100% of configured floors
  • degraded-imf / degraded-voting: 85% of floors
  • title-only: 75% of floors
  • minimal: 65% of floors

Tradecraft Quality Signals

In addition to line floors, the following tradecraft signals are always RED (blocking) regardless of --strict mode:

Signal Requirement Artifacts Affected
WEP Band Every headline judgement must carry a WEP (Words of Estimative Probability) confidence band + time horizon 12 artifacts (executive-brief, scenario-forecast, forward-projection, threat-model, etc.)
Admiralty Grade Every external source must carry an Admiralty Code grade (A1–F6) 13 artifacts (intelligence assessments, comparatives, historical parallels)
≥10 SATs per run At least 10 Structured Analytic Techniques applied and documented in methodology-reflection.md methodology-reflection.md §12
Mermaid diagrams Required structural diagrams present Per-artifact requirements in artifact-catalog.md
Required sections Template-mandated sections present All templates with ## Required Sections headers

ICD-203 / WEP Confidence Framework

The intelligence assessments follow the US Intelligence Community Directive 203 (ICD-203) confidence framework adapted for political intelligence:

WEP Band Probability Range Usage
Almost certain 93–99% Reserved for near-term procedural certainties
Very likely 80–92% Strong evidence, limited alternatives
Likely 63–79% Preponderance of evidence supports
Roughly even 40–62% Evidence supports multiple outcomes equally
Unlikely 20–39% Limited evidence against dominant view
Very unlikely 5–19% Minimal evidence, contrarian scenarios
Remote 1–4% Black swan / wildcard territory

Admiralty Source Grading

Reliability Credibility Combined Grade
A Completely reliable 1 Confirmed A1 (highest)
B Usually reliable 2 Probably true B2
C Fairly reliable 3 Possibly true C3
D Not usually reliable 4 Doubtful D4
E Unreliable 5 Improbable E5
F Cannot be judged 6 Cannot be judged F6 (lowest)

EP Official Journal and adopted texts are rated A1; MCP feed data is rated B2; press reports are rated C3 unless corroborated.

🔄 Continuous Improvement

Planned Enhancements

See FUTURE_WORKFLOWS.md for:

  • Advanced security scanning
  • Performance testing enhancements
  • Deployment automation improvements
  • Multi-environment support
  • Fuzzing integration

📚 Related Documentation

Document Focus Link
🔐 Security Architecture Current security implementation SECURITY_ARCHITECTURE.md
📈 Security Flowcharts Process flows with security controls FLOWCHART.md
📊 Data Model Data structures and flows DATA_MODEL.md
🏛️ Architecture System structure (§Analysis Framework) ARCHITECTURE.md
🚀 Future Workflows Planned enhancements FUTURE_WORKFLOWS.md
📋 Release Process Release procedures docs/RELEASE_PROCESS.md
🛡️ ISMS Policy Security policy framework Hack23 ISMS-PUBLIC
📦 Dependabot Config Automated dependency updates .github/dependabot.yml
🔬 Analysis Methodologies 22 intelligence methodologies analysis/methodologies/
📄 Analysis Templates 60 artifact templates analysis/templates/
📖 Prompt Library 13-file prompt architecture .github/prompts/

📞 Questions? Contact: Security Team
🔐 Security Issues? See SECURITY.md for vulnerability disclosure

🔗 Related ISMS-PUBLIC Policies

Last updated: 2026-05-28 by Documentation Architect / Security Architect (EU Parliament Monitor v0.9.26)