feat(metric): Flow Load — WIP per ISO week + author concurrency

[trentas]

Summary

• Adds the Flow Load metric: per-ISO-week count of PRs in flight, segmented by PR intent (FEATURE / FIX / REFACTOR / CONFIG / UNKNOWN) classified from the PR title, plus a separate per-week count of distinct commit authors (engineering-parallelism proxy)
• Extends the PR model + GitHub reader to fetch open and closed-without-merge PRs (needed to count what was in flight during a window, not just what merged)
• Wires the new field through the full metric chain (aggregator → schema → writer → narrative → TS types → platform UI → docs/METRICS.md)

Closes #16.

Why this matters

AI assistants tend to expand the amount of in-flight work faster than they compress lifecycle time. Without measuring WIP simultâneo, "more PRs/week" looks like throughput when it's actually congestion. The intent breakdown surfaces a specific pattern Kersten flags in Project to Product — features piling up in parallel while fixes/refactors stagnate.

Key design notes

• No per-author leak. author_concurrency exposes only the count of distinct authors per week; the author list stays local to flow_load.py. This is intentional and documented in the module + docs/METRICS.md (Principle build(deps): Bump actions/checkout from 4 to 6 #2).
• Engineering WIP, not product WIP. Backlog, design, and local-branch work do not appear — the UI subtitle calls this out.
• PR intent via title for v0; aggregating from PR commits is left as an explicit follow-up to validate empirically (called out in the issue too).
• Narrative thresholds are hypotheses. FLOW_LOAD_FEATURE_GROWTH_MULTIPLIER = 1.5 / MIN_ABSOLUTE = 2 need calibration against 3–5 repos before they earn their keep.

What changed

Engine

• iris/models/pull_request.py — merged_at now optional; new closed_at, state: Literal["open"|"closed"|"merged"]
• iris/ingestion/github_reader.py — fetches open + closed + merged states, filters by window overlap
• iris/analysis/{pr_lifecycle,activity_timeline,acceptance_rate}.py — filter to state == "merged" where semantics require it
• iris/analysis/flow_load.py (new) — analyze_flow_load(prs, commits, *, bucket="week")
• iris/metrics/aggregator.py + iris/models/metrics.py — flow_load field on ReportMetrics
• iris/i18n.py + iris/reports/narrative.py — descriptive finding + (calibration-pending) feature-growth finding

Platform

• platform/src/types/metrics.ts — FlowLoadWeek interface + optional flow_load field
• platform/src/app/[tenant]/repos/[repoName]/{page,charts}.tsx — FlowLoadCard using recharts ComposedChart (stacked area by intent + author_concurrency line on right axis)
• platform/lib/translations.ts — flowLoad.* strings in en-US and pt-BR

Docs & tests

• docs/METRICS.md — new section 24 with the overlap rule, edge cases, coverage limitations, and privacy notes
• tests/test_flow_load.py (10 cases) + tests/test_github_reader_state.py (5 cases)

Test plan

• python -m pytest tests/ — 80 passing (15 new)
• cd platform && npx tsc --noEmit — clean
• npx eslint on changed files — clean
• Verify FlowLoadCard renders end-to-end against a real payload — not done in this PR because flow_load only appears in payloads emitted by an Iris CLI running this branch's analyzer against a repo with PR data. The card is guarded by length >= 2, so it stays hidden until that ships.

Explicit follow-ups (called out in the issue)

• Branch concurrency proxy via merge-commit reconstruction — skipped for v0 pending coverage check (issue notes <50% coverage as a possible reason to deprecate)
• PR intent via PR-commit aggregation vs PR title — measure empirically and pick the more robust path
• Calibrate FLOW_LOAD_FEATURE_GROWTH_* thresholds with 3–5 real repos before relying on the finding

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clickbus-iris	Ready	Preview, Comment	May 12, 2026 8:15pm