🤝 Contributing — Riksdagsmonitor

🛡️ Secure Contribution Guidelines
🎯 Building Democratic Transparency Through Collaborative Excellence

📋 Document Owner: CEO | 📄 Version: 1.0 | 📅 Last Updated: 2026-02-20 (UTC)
🔄 Review Cycle: Quarterly | ⏰ Next Review: 2026-05-20
🏢 Owner: Hack23 AB (Org.nr 5595347807) | 🏷️ Classification: Public

🎯 Purpose Statement

This contributing guide establishes secure contribution procedures for Riksdagsmonitor, implementing Secure Development Policy and Change Management from Hack23 AB's ISMS framework.

We believe in security through transparency and continuous improvement, welcoming contributions that enhance democratic transparency while maintaining our high security standards.

— James Pether Sörling, CEO/Founder

Contributing

Hi there! We're thrilled that you'd like to contribute to Riksdagsmonitor. Your help is essential for keeping it great.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Issues and PRs

If you have suggestions for how this project could be improved, or want to report a bug, open an issue! We'd love all and any contributions. If you have questions, too, we'd love to hear them.

We'd also love PRs. If you're thinking of a large PR, we advise opening up an issue first to talk about it, though! Look at the links below if you're not sure how to open a PR.

Submitting a Pull Request

Fork and clone the repository.
Install dependencies: npm install
Make sure the tests pass on your machine: npm test
Create a new branch: git checkout -b my-branch-name
Make your change, add tests, and make sure the tests still pass.
Validate HTML: npm run htmlhint
Push to your fork and submit a pull request.
Pat yourself on the back and wait for your pull request to be reviewed and merged.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

Follow the existing code style (HTML5 semantic markup, CSS custom properties, mobile-first design)
Write and update tests (Vitest for unit tests, Cypress for E2E)
Keep your changes as focused as possible
Ensure WCAG 2.1 AA accessibility compliance
Validate HTML with HTMLHint before submitting
Write a good commit message

Work in Progress pull requests are also welcome to get feedback early on.

🏗️ Project Structure

Directory	Purpose
`*.html`	Multi-language index pages (14 languages)
`styles.css`	Cyberpunk theme design system
`js/`	Dashboard JavaScript modules (Chart.js, D3.js, Mermaid init)
`dashboard/`	Interactive intelligence dashboards
`news/`	Rendered political news articles (`$DATE-$SUB-$LANG.html`)
`analysis/daily/$DATE/$SUB/`	Per-day analysis artifacts consumed by the aggregator
`analysis/methodologies/`	Editorial method files (source of truth for how analysis is done)
`analysis/templates/`	Output section templates (source of truth for what goes in an article)
`scripts/aggregate-analysis.ts`	Concatenates daily artifacts → canonical `article.md` + manifest
`scripts/render-articles.ts` + `scripts/render-lib/`	Markdown → sanitised HTML (unified / remark / rehype)
`scripts/`	Other build, generation, and utility scripts
`tests/`	Vitest unit tests
`cypress/`	Cypress E2E tests
`cia-data/`	CIA platform data exports

📰 How to add a new news type

The legacy content-generator approach (generate-news-enhanced, article-template) has been removed. To add a new news type:

Pick a subfolder slug (e.g. interpellations-deep) — this becomes analysis/daily/$DATE/$SUB/.
Register it in the aggregator section-order config under analysis/templates/ — this determines narrative flow without touching TypeScript.
Copy an existing per-type workflow .md from .github/workflows/news-*.md (e.g. news-propositions.md) and adapt:
- analysis phase: the specific MCP queries the new type needs
- analysis gate: the per-type 9-artifact or 14-artifact list (see .github/prompts/05-analysis-gate.md)
- front-matter: schedule, subfolder slug, description
Compile with gh aw compile to produce the matching .lock.yml.
Never hand-write localised HTML. The per-type workflow only produces $DATE-$SUB-en.html + $DATE-$SUB-sv.html; the rest are the sole responsibility of the news-translate workflow.

See WORKFLOWS.md §5 for the full agentic-workflow structure, and ARCHITECTURE.md §"News Generation Pipeline Architecture" for the aggregator/renderer contract.

✅ Quality Gates

All PRs must pass these quality gates before merge:

Check	Tool	Purpose
HTML Validation	HTMLHint	Standards compliance
Link Checking	Linkinator	Verify internal/external links
JavaScript Linting	ESLint	Code quality
Unit Tests	Vitest	Functionality verification
Security Scanning	CodeQL, Dependabot	Vulnerability detection
Secret Scanning	GitHub	Credential leak prevention

🌐 Multi-Language Support

Riksdagsmonitor supports 14 languages. When making content changes:

Update all affected language files
Use lang attribute on <html> tags
Support RTL for Arabic (index_ar.html) and Hebrew (index_he.html)
Include hreflang tags for SEO
See TRANSLATION_GUIDE.md for vocabulary reference

🤖 GitHub Copilot Agents

This project has 14 specialized GitHub Copilot agents to assist development:

security-architect — Security architecture and ISMS compliance
documentation-architect — C4 models and technical documentation
quality-engineer — HTML/CSS validation and accessibility
frontend-specialist — Responsive design and multi-language support
intelligence-operative — Political data analysis
content-generator — Automated news generation

Learn more in AGENTS.md.

Resources

🛠️ Development & Security Policies

🛠️ Secure Development Policy — Development security standards
📝 Change Management — Change control procedures
🔐 Information Security Policy — Overall security governance
🔍 Vulnerability Management — Security testing and remediation

📝 Project Documentation

📋 README — Project overview and classification
🔐 Security Policy — Vulnerability reporting
📜 Code of Conduct — Community standards
🏗️ Architecture — System architecture
🔧 Workflows — CI/CD documentation
🧪 Testing — Test strategy and coverage

📋 Document Control:
✅ Approved by: James Pether Sörling, CEO
📤 Distribution: Public
🏷️ Classification:
📅 Effective Date: 2026-02-20
⏰ Next Review: 2026-05-20
🎯 Framework Compliance:

🔗 Hack23 Ecosystem

🌐 Platforms	📦 Open-Source Projects	🛡️ Governance & Standards
🗳️ Riksdagsmonitor — Swedish Parliament intelligence 🇪🇺 EU Parliament Monitor — European coverage 🕵️ Citizen Intelligence Agency — political-data engine 🌐 Hack23 AB — corporate site 📰 Hack23 Blog — engineering & policy 💼 Hack23 on LinkedIn	🗳️ Hack23/riksdagsmonitor 🕵️ Hack23/cia 🇪🇺 Hack23/euparliamentmonitor 🔌 Hack23/european-parliament-mcp ✅ Hack23/cia-compliance-manager 🥋 Hack23/black-trigram 🏠 Hack23/homepage	🛡️ Hack23 ISMS-PUBLIC — public ISMS 🔒 Information Security Policy 🤖 AI Policy 🧪 Secure Development Policy 🎯 Threat Modeling Policy ⚠️ Vulnerability Management 🏷️ Classification Framework