Improve architecture and quality of agentic workflows: extract embedded code, enforce bounded contexts, and add strict-typed TypeScript

[pethers]

📋 Issue Type

Architecture / Code Quality / Testing

🎯 Objective

Identify and implement improvement areas across all 14 agentic workflows (.github/workflows/news-*.md), the prompt library (.github/prompts/), and compiled workflows (.github/workflows/news-*.lock.yml). Goals:

1. Extract embedded code from agentic workflow Markdown sources and prompt modules into well-architected, strict-typed TypeScript modules with high-quality tests
2. Enforce bounded contexts — each component has a single responsibility with explicit interfaces
3. Improve test quality — ensure extracted modules have unit tests with >90% coverage

📊 Current State

• 14 agentic workflows in .github/workflows/news-*.md contain inline bash/TypeScript logic embedded in prompt text
• 13 prompt modules in .github/prompts/ define analysis pipeline logic, gate checks, and article generation rules inline
• Embedded code is untestable, untyped, and duplicated across workflows
• No TypeScript compilation or lint checking of code embedded in Markdown
• Existing scripts like aggregate-analysis.ts, render-articles.ts, validate-methodology-reflection.ts already demonstrate the target architecture pattern

🚀 Desired State

Architecture Improvements

• All reusable logic extracted from Markdown into scripts/ subdirectories with bounded contexts:
  • scripts/agentic/ — Workflow orchestration helpers (gate validation, artifact inventory)
  • scripts/analysis/ — Analysis pipeline logic (artifact checking, quality scoring)
  • scripts/prompts/ — Prompt-related utilities (template rendering, variable substitution)
• Each module has explicit TypeScript interfaces and type exports
• Clear dependency graph between modules (no circular dependencies)

Code Quality

• All extracted code passes eslint with zero warnings
• Strict TypeScript (strict: true, noUncheckedIndexedAccess: true)
• No any types — use proper interfaces for all data structures
• JSDoc documentation on all public functions

Test Quality

• Every extracted module has a co-located .test.ts file
• Unit tests cover success paths, error paths, and edge cases
• Tests use Vitest with proper mocking patterns (consistent with existing test suite)
• Integration tests validate end-to-end workflow artifact production

🔧 Implementation Approach

1. Audit phase: Inventory all inline code in news-*.md and .github/prompts/*.md files
2. Design phase: Define bounded context boundaries and TypeScript interfaces
3. Extract phase: Move code to typed modules in scripts/ with proper exports
4. Test phase: Write comprehensive unit and integration tests
5. Integrate phase: Update workflows to call extracted modules instead of inline code
6. Validate phase: Ensure all existing workflow behavior is preserved

📚 Key Files to Analyse

File/Directory	Purpose
.github/workflows/news-*.md (14 files)	Agentic workflow sources — contain embedded bash/TS
.github/prompts/00-base-contract.md	Role definition, AI-FIRST rule, pipeline order
.github/prompts/03-data-download.md	Download pipeline with embedded logic
.github/prompts/04-analysis-pipeline.md	23-artifact production rules
.github/prompts/05-analysis-gate.md	Blocking gate validation logic
.github/prompts/06-article-generation.md	Article generation rules
.github/prompts/ext/tier-c-aggregation.md	Tier-C aggregation additive rules
.github/prompts/ext/long-horizon-forecasting.md	Horizon stratification rules
WORKFLOWS.md	Workflow architecture documentation
scripts/validate-methodology-reflection.ts	Existing validation pattern to follow
scripts/aggregate-analysis.ts	Existing aggregation pattern to follow

✅ Acceptance Criteria

• All inline code from agentic workflows extracted to typed TypeScript modules
• Each module has explicit interfaces and type exports (zero any)
• Bounded context separation enforced (no module > 300 lines)
• Every extracted module has a .test.ts file with >90% line coverage
• ESLint passes with zero warnings on new code
• Existing workflow behavior verified via integration tests
• WORKFLOWS.md updated to document new module architecture
• No regression in npm test (all 3,319+ existing tests pass)
• knip reports no new dead code

🤖 Recommended Agent

code-quality-engineer — Code refactoring, TypeScript architecture, bounded contexts, test quality

🏷️ Labels

enhancement, agentic-workflow, refactor, testing, component:ai-workflows, priority-high, size-xl

[pethers]

🔗 Related Issues (Architecture & Quality Improvement Series)

This issue is part of a coordinated effort to improve architecture, code quality, and test coverage across the riksdagsmonitor platform:

1. Improve architecture and quality of agentic workflows: extract embedded code, enforce bounded contexts, and add strict-typed TypeScript #2279 — Agentic workflows: extract embedded code, enforce bounded contexts (this issue)
2. Resolve all ESLint warnings, improve strict typing, fix knip issues, and enhance TypeDoc/reporting configuration #2276 — ESLint warnings, strict typing, knip, TypeDoc/reporting
3. Improve architecture, code quality, and test coverage for article.md generation pipeline (aggregate-analysis → article.md) #2277 — article.md generation pipeline (aggregate-analysis)
4. Improve architecture, code quality, and test coverage for HTML/XML/RSS/sitemap generation from article.md (render-articles pipeline) #2278 — HTML/XML/RSS/sitemap rendering pipeline (render-articles)

Dependency order: #2276 (tooling/linting) should be addressed first to establish baseline quality gates, then #2279 and #2277 can proceed in parallel, with #2278 following #2277 since they share bounded context interfaces.