🔄 Full review & update: FLOWCHART.md, STATEDIAGRAM.md, WORKFLOWS.md — Current-state processes, states & DevOps

[pethers]

📋 Issue Type

Documentation — Process flows, state diagrams, and workflow documentation deep review

🎯 Objective

Perform a complete deep-inspection review and update of FLOWCHART.md (v1.2), STATEDIAGRAM.md (v1.1), and WORKFLOWS.md (v7.4) to ensure they accurately reflect the current state of all processes, state transitions, and CI/CD pipelines as of v0.8.76 with extensive coverage of political intelligence workflows and analysis gate processes.

📊 Current State Assessment

• FLOWCHART.md v1.2 (2026-04-20) — 16 days behind; missing political intelligence generation flows
• STATEDIAGRAM.md v1.1 (2026-04-20) — missing analysis artifact lifecycle states
• WORKFLOWS.md v7.4 (2026-05-05) — most current but needs v0.8.76 reconciliation
• 50 workflow files total (22 .yml + 14 .md + 14 .lock.yml)
• Political intelligence pipeline with 39 analysis templates and 18 methodologies
• Analysis gate with checks 1-9b validation
• Horizon stratification (T+72h → T+1460d) for forward-look articles
• Build chain: prebuild → build → postbuild with multiple script phases

🔧 Required Updates — FLOWCHART.md

Political Intelligence Production Flows

• Document full political intelligence generation pipeline: generate-political-intelligence.ts → catalog → daily-streams → render
• Add analysis artifact production flow (23 artifacts across Families A-D)
• Document analysis gate validation flow (checks 1-9b in scripts/agentic/analysis-gate.ts)
• Add per-document analysis flow (methodology-reflection, significance-scoring, political-classification)
• Document horizon-specific flows (T+72h, T+7d, T+30d, T+90d, T+365d, T+1460d)
• Add scenario analysis and coalition mathematics calculation flows
• Document OSINT tradecraft standard integration in intelligence workflows

News Generation & Publishing Flows

• Update agentic news pipeline for 14 workflows with full MCP tool call sequences
• Document aggregate-analysis.ts deterministic analysis aggregation flow
• Document render-articles.ts --all --lang all rendering pipeline
• Add translation validation flow for 14 languages including RTL
• Document news metadata extraction → RSS → sitemap → indexes chain

Data Pipeline Flows

• Document parliamentary data download flow (download-parliamentary-data.ts, fetch-voting-records.ts, fetch-calendar.ts)
• Document economic data fetch flows (IMF: imf-fetch.ts commands; SCB: scb-fetch.ts; WB: world-bank-context.ts)
• Add Statskontoret and RiR followups data flows
• Document CIA schema governance flow (sync → validate → check-updates → generate-types)

Build & Deploy Flows

• Verify prebuild chain accuracy: generate-news-indexes → extract-news-metadata → generate-sitemap-html → generate-rss → generate-sitemap
• Document library build: tsc -p tsconfig.lib.json && tsc -p tsconfig.npm-scripts.json
• Document dual deployment: AWS S3 + GitHub Pages
• Add dashboard build flows (coalition, committees, politician)

🔧 Required Updates — STATEDIAGRAM.md

Analysis Artifact Lifecycle

• Add state diagram for 23-artifact analysis folder: empty → populated → gate-checked → passed → consumed-by-article
• Document analysis gate check states: pending → check-1 → ... → check-9b → passed/failed
• Add methodology-reflection document states: drafted → validated → referenced
• Document political classification states per document

Political Intelligence States

• Add intelligence assessment lifecycle: collection → processing → analysis → dissemination → feedback
• Document scenario analysis states: hypothesis → evidence-gathering → assessment → confidence-labeling
• Add election-cycle analysis states aligned with parliamentary calendar
• Document PIR (Priority Intelligence Requirements) roll-forward states

Existing State Diagrams to Verify

• News article lifecycle (draft → validation → translation → publish → supersede)
• Agentic workflow states (queued → running → safe-output → PR → merge/rollback)
• CIA data refresh states (scheduled → download → validate → diff → PR → merge → deploy)
• Release pipeline states (tag → build → attest → publish → deploy → invalidate)
• Incident state machine (detected → triaged → contained → eradicated → recovered → post-mortem)
• npm package lifecycle states

🔧 Required Updates — WORKFLOWS.md

Current Toolchain Reconciliation

• Verify: TypeScript 6.0.3, Vite 8.0.10, Vitest 4.1.5, Cypress 15.14.1, Node.js ≥26
• Verify current test count baseline (package version 0.8.76)
• Update any version references that have drifted

Political Intelligence Workflow Coverage

• Document political intelligence generation as a CI/CD concern
• Add analysis gate enforcement in the build/validation pipeline
• Document methodology-reflection validation (validate-methodology-reflection.ts)
• Cover quality score validation (validate-quality-scores.cjs)
• Document article validation (validate-article.ts)

Agentic Workflow Details

• Verify all 14 agentic news workflow names and schedules
• Document the five-layer safe-output security model in detail
• Add egress firewall configuration (Squid + iptables allowlists)
• Document MCP server interactions per workflow
• Cover horizon-specific workflow patterns (week-ahead, month-ahead, quarter-ahead, year-ahead, election-cycle)

✅ Acceptance Criteria

• All three documents reflect v0.8.76 current state
• All Mermaid flowcharts, state diagrams, and sequence diagrams render correctly
• Political intelligence methods and analysis gate processes have extensive coverage
• Every workflow file in .github/workflows/ is documented
• Version bumped, changelog entry added for each document
• No placeholder or aspirational content — only verifiable current facts
• Cross-references between the three documents are consistent

🤖 Recommended Agent

documentation-architect — Process flow and state diagram expertise with Mermaid

📚 References

• Current: FLOWCHART.md v1.2, STATEDIAGRAM.md v1.1, WORKFLOWS.md v7.4
• scripts/agentic/analysis-gate.ts — Checks 1-9b implementation
• scripts/agentic/artifact-inventory.ts — 23 artifacts (Families A-D)
• scripts/political-intelligence/ — catalog, daily-streams, i18n, render
• scripts/validate-methodology-reflection.ts — Methodology validation
• .github/workflows/README.md — Workflow inventory
• analysis/methodologies/ — 18 methodology files
• analysis/templates/ — 39 template files

🏷️ Labels

documentation, architecture