🤝 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

1. Fork and clone the repository.
2. Install dependencies: npm install
3. Make sure the tests pass on your machine: npm test
4. Create a new branch: git checkout -b my-branch-name
5. Make your change, add tests, and make sure the tests still pass.
6. Validate HTML: npm run htmlhint
7. Push to your fork and submit a pull request.
8. 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:

1. Pick a subfolder slug (e.g. interpellations-deep) — this becomes analysis/daily/$DATE/$SUB/.
2. Register it in the aggregator section-order config under analysis/templates/ — this determines narrative flow without touching TypeScript.
3. 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
4. Compile with gh aw compile to produce the matching .lock.yml.
5. 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

• How to Contribute to Open Source
• Using Pull Requests
• GitHub Help

---

📚 Related Documents

🛠️ 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

🗳️ Empower citizens · 🔍 Strengthen democratic accountability · 🕵️ Illuminate the political process

_{© 2008–2026 Hack23 AB (Org.nr 559534-7807) · Maintainer: James Pether Sörling, CISSP CISM}