Expand the week/1 month/1 year / all time filters to add: 6 months and since start of year

[exploreriii]

🧑‍🎓 Beginner Issue — a well-scoped task for contributors ready to learn this codebase and own a small implementation.
Time: ~8 hours · Prerequisites: ~1 completed Good First Issue recommended; comfortable forking, branching, and opening a PR without a tutorial.
If that feels unfamiliar, a Good First Issue is the more rewarding path right now — you can always come back.

The task

Problem:
For many of our tables, we allow users to select their view between week, 1 month, 1 year or all time dataviews.

We should also enable:

• 6 months
• Since start of year

As there is a big jump in insight between 1 month and 1 year
Also, people also only care about since Jan 2026 data, for example

What done looks like:
Add these two time filter options and ensure all the charts render as expected

How to work on this

1. Claim it: comment /assign and wait to be assigned — unassigned PRs are closed automatically.
2. Get a plan: once assigned, comment @coderabbitai plan for a draft implementation plan. Verify it against the code — spotting where it's wrong is the research.
3. Research before coding: read the files above and their tests; most of the value of this level is building an accurate picture before changing anything. The workflow guide has the mechanics.

🤖 AI: tools are welcome; verified work is required. You ran it, you can explain every line, your tests verify behaviour — see the AI policy. Fully automated bot PRs are closed.

Before opening your PR:

• I spent real time reading the relevant code before writing any
• The implementation works and follows the surrounding patterns
• I added basic unit tests for what I changed, in the mirrored path tests/<pkg>/test_<module>.py (testing guide)
• uv run pytest and uv run ruff check src tests pass; scope is limited to this issue
• The basics from your first issue still apply — signed commits, linked issue, clean history (quick refs)

Stuck? Comment here with what you've tried — see getting help.

[coderabbitai]

Coding Plan

Summary

• Extend the Period model in domain/periods.py with a declarative anchor field and an is_all_time property, then add "6 months" (fixed 182-day window) and "since start of year" (calendar-anchored) to ACTIVITY_PERIODS.
• Route the calendar-anchored cutoff through the pipelines by using the existing is_active_since primitive in role_coverage/team_activity, and by carrying a cutoff datetime (instead of an integer day count) through the difficulty and maintainer chart spans.
• Keep the export layer and frontend generic; only adjust the API_PERIODS filter, the hardcoded vocabulary test, and the frontend fixtures/order assertion.

Design Choices

Design Choice 1: Model representation for the calendar-anchored "since start of year" period

Options Considered:

1. Add a declarative anchor field (for example anchor="year_start") and branch inside Period.cutoff().
2. Add a cutoff_fn: Callable[[datetime], datetime] override stored on each Period.
3. Recompute a dynamic integer days value at each pipeline run and store it back into the tuple entry.

Chosen Option: 1

Rationale: A declarative anchor field keeps Period frozen, serializable, and easy to unit test. It avoids storing callables in a data model or mutating a frozen tuple.

Design Choice 2: Computation of per-period active/quiet thresholds for the calendar-anchored period

Options Considered:

1. Add an optional cutoff parameter to the affected functions and call is_active_since when it is supplied; otherwise keep the existing day-count path.
2. Recompute an integer day count from the cutoff ((now - cutoff).days) in the pipeline and keep passing an integer.

Chosen Option: 1

Rationale: This option reuses the existing but unused is_active_since primitive. It avoids day-truncation errors near the anchor date. It keeps the existing semantic-threshold defaults (ROLE_ACTIVE_DAYS, GONE_DARK_DAYS) unchanged.

Design Choice 3: Day count and tab order for the new periods

Options Considered:

1. "6 months" as 182 days; order the tabs 7d, 30d, 182d, 365d, then "since start of year".
2. "6 months" as 180 days; other orderings.

Chosen Option: 1

Rationale: 182 days is half of 365 and matches the existing fixed-window style. Placing "since start of year" after "1 year" keeps the shortest-first ordering that the frontend and its tests expect, because its span can reach up to a full year.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Extend the period model and vocabulary

This phase teaches the Period model to express a calendar-anchored window and adds the two new period entries. It also updates the one export-layer filter and the one test that hardcode the fixed-window assumption. After this phase, the new tabs appear in the dashboard automatically for every generic period consumer.

Task 1: Add calendar-anchored cutoff support to the `Period` model

Extend the domain model so a period can express a cutoff that is not a fixed rolling window.

• Update src/hiero_analytics/domain/periods.py. Add an optional anchor field to Period (for example anchor: str | None = None) with the documented value "year_start".
• Extend Period.cutoff(now) to return January 1 of now.year (preserving now's timezone) when anchor == "year_start". Keep the existing rolling-window branch (now - timedelta(days=self.days)) and the all-time branch (None).
• Add an is_all_time property that returns True only when both days is None and anchor is None. Use this to distinguish "all time" from a calendar-anchored window, because a calendar-anchored window has days is None but still produces a real cutoff.

Task 2: Add the "6 months" and "since start of year" periods

Register the two new periods in the single vocabulary tuple.

• Update ACTIVITY_PERIODS in src/hiero_analytics/domain/periods.py.
• Add Period("182d", "6 months", 182) between the 30d and 365d entries.
• Add Period("ytd", "Since start of year", anchor="year_start") after the 365d entry.
• Keep the default=True flag on the 30d entry unchanged.

Task 3: Update the export layer to publish the calendar-anchored period

Ensure the calendar-anchored period is not filtered out of the API.

• Update API_PERIODS in src/hiero_analytics/export/data_api.py. Change the filter from period.days is not None to not period.is_all_time, so the "ytd" period (which has days=None) is still published as a variant and label.
• No change is required for _period_variants or the manifest period_labels, because both iterate API_PERIODS generically.
• Confirm export/macro_metrics.py still resolves "30d" by key and needs no change.

Task 4: Update and extend the period domain tests

Update the one test that hardcodes the vocabulary and add tests for the new behavior.

• Update tests/domain/test_periods.py. Extend the hardcoded vocabulary assertion to include the 182d and ytd entries in the chosen order.
• Add a test that Period("ytd", ..., anchor="year_start").cutoff(now) returns January 1 of now.year with the correct timezone.
• Add a test for is_all_time that distinguishes the calendar-anchored period from a true all-time sentinel.

🤖 Prompt for AI agents

Implement changes to the period domain model and vocabulary so the dashboard can
express a calendar-anchored time range, then propagate this through the export
layer and tests.

- In `src/hiero_analytics/domain/periods.py`:
- Add an optional `anchor: str | None = None` field to the `Period` dataclass,
with the documented value `"year_start"`.
- Extend `Period.cutoff(now)` so that when `anchor == "year_start"`, it returns
January 1 of `now.year`, preserving `now`'s timezone. Keep the existing
rolling-window branch (`now - timedelta(days=self.days)`) and the all-time
branch (`None`) unchanged.
- Add an `is_all_time` property that returns `True` only when both `days is
None` and `anchor is None`.
- In `ACTIVITY_PERIODS`, insert `Period("182d", "6 months", 182)` between the
30d and 365d entries, and append `Period("ytd", "Since start of year",
anchor="year_start")` after the 365d entry. Keep `default=True` on the 30d entry
unchanged.
- In `src/hiero_analytics/export/data_api.py`, change the `API_PERIODS` filter
from `period.days is not None` to `not period.is_all_time`, so the `"ytd"`
period is still published. Do not change `_period_variants` or the manifest
`period_labels`. Confirm `export/macro_metrics.py` still resolves `"30d"` by key
without modification.
- In `tests/domain/test_periods.py`: extend the hardcoded vocabulary assertion
to include the `182d` and `ytd` entries in the correct order; add a test
asserting `Period("ytd", ..., anchor="year_start").cutoff(now)` returns January
1 of `now.year` with the correct timezone; add a test for `is_all_time` that
distinguishes the calendar-anchored period from a true all-time sentinel.

Phase 2: Support calendar-anchored thresholds in the pipelines

This phase updates the consumers that treat a period as a fixed integer day count. It routes the calendar-anchored cutoff through the analysis functions using the existing is_active_since primitive, and through the chart-span builders as a cutoff datetime.

Task 1: Accept a cutoff in the role-coverage and team-activity analysis functions

Let the analysis layer decide activity by an exact cutoff when one is supplied.

• Update src/hiero_analytics/analysis/role_coverage.py. Add an optional cutoff parameter to build_repo_role_coverage, find_unbadged_role_work, and find_globally_quiet_role_holders. When the cutoff is supplied, decide active/quiet status with is_active_since(last_active, cutoff); otherwise keep the existing is_active(last_active, now, within_days) path.
• Update src/hiero_analytics/analysis/team_activity.py. Add the same optional cutoff parameter to build_team_activity_summary and its _aggregate helper, and use is_active_since when the cutoff is supplied.
• Keep the existing int | None day-count parameters and their ROLE_ACTIVE_DAYS/GONE_DARK_DAYS defaults, so the semantic-threshold callers are unchanged.

Task 2: Route the period cutoff through the role-coverage pipeline

Pass a cutoff for the calendar-anchored period, and keep day counts for fixed windows.

• Update src/hiero_analytics/pipelines/role_coverage.py. For each period, when period.days is None (the calendar-anchored period), pass period.cutoff(now) into the new cutoff parameters of find_globally_quiet_role_holders, build_repo_role_coverage (via _build_role_coverage), and build_team_activity_summary. Otherwise keep passing period.days as today.
• The existing record pre-filtering already uses period.cutoff(now), so it needs no change.

Task 3: Carry a cutoff datetime through the difficulty and maintainer chart spans

Replace the integer day-count span value with a cutoff datetime so calendar-anchored spans work.

• Update src/hiero_analytics/pipelines/difficulty.py. Build each span with period.cutoff(now) instead of period.days, keeping None for the "All time" span. Update _run_window to accept a cutoff: datetime | None and use it directly (epoch or skip-filter when None) instead of computing now - timedelta(days=window_days).
• Update src/hiero_analytics/analysis/difficulty_analysis.py only if its _run_window callee still derives a cutoff from a day count; its issues_labeled_since/issues_unlabeled_created_since already accept a cutoff datetime.
• Update src/hiero_analytics/pipelines/maintainer_pipeline.py. Build each span with period.cutoff(now) and pass the cutoff into build_maintainer_repo_pipeline.
• Update src/hiero_analytics/analysis/maintainer_pipeline.py. Change build_maintainer_repo_pipeline to accept a cutoff datetime (or None for all time) instead of active_window_days, and filter stage_df["occurred_at"] >= cutoff directly.
• Keep the human-readable span labels (period.label) and filename suffixes (period.key) as today.

Task 4: Add pipeline and analysis tests for the calendar-anchored period

Follow the existing inline-datetime test style.

• Add a test in tests/domain/test_recency.py-style form for the calendar-anchored active check if not already covered, mirroring test_is_active_since_compares_timestamps_exactly.
• Add tests in tests/analysis/test_role_coverage.py and tests/analysis/test_team_activity.py that supply a cutoff datetime and assert "active"/"quiet" status, following the existing inline datetime(..., tzinfo=UTC) and _ev(...) factory pattern.
• Confirm the generic tests (tests/contracts/test_output_contract.py, tests/pipelines/test_difficulty.py) pick up the new period keys automatically; extend any assertion that references a fixed set of period suffixes.

🤖 Prompt for AI agents

Update the pipeline and analysis consumers that currently treat a period as a
fixed integer day count, so the calendar-anchored "since start of year" period
works correctly.

- In `src/hiero_analytics/analysis/role_coverage.py`: add an optional cutoff
parameter to `build_repo_role_coverage`, `find_unbadged_role_work`, and
`find_globally_quiet_role_holders`. When a cutoff is supplied, use
`is_active_since(last_active, cutoff)` to decide active/quiet status; otherwise
keep the existing `is_active(last_active, now, within_days)` path. Keep the
existing `int | None` day-count parameters and their
`ROLE_ACTIVE_DAYS`/`GONE_DARK_DAYS` defaults unchanged.
- In `src/hiero_analytics/analysis/team_activity.py`: add the same optional
cutoff parameter to `build_team_activity_summary` and its `_aggregate` helper,
using `is_active_since` when the cutoff is supplied.
- In `src/hiero_analytics/pipelines/role_coverage.py`: for each period, when
`period.days is None` (the calendar-anchored period), pass `period.cutoff(now)`
into the new cutoff parameters of `find_globally_quiet_role_holders`,
`build_repo_role_coverage` (via `_build_role_coverage`), and
`build_team_activity_summary`. Otherwise keep passing `period.days` as today. Do
not change the existing record pre-filtering, since it already uses
`period.cutoff(now)`.
- In `src/hiero_analytics/pipelines/difficulty.py`: build each span with
`period.cutoff(now)` instead of `period.days`, keeping `None` for the "All time"
span. Update `_run_window` to accept a `cutoff: datetime | None` and use it
directly (epoch or skip-filter when `None`) instead of computing `now -
timedelta(days=window_days)`.
- In `src/hiero_analytics/analysis/difficulty_analysis.py`: update only if its
`_run_window` callee still derives a cutoff from a day count; note that
`issues_labeled_since`/`issues_unlabeled_created_since` already accept a
`cutoff` datetime.
- In `src/hiero_analytics/pipelines/maintainer_pipeline.py`: build each span
with `period.cutoff(now)` and pass the cutoff into
`build_maintainer_repo_pipeline`.
- In `src/hiero_analytics/analysis/maintainer_pipeline.py`: change
`build_maintainer_repo_pipeline` to accept a cutoff datetime (or `None` for all
time) instead of `active_window_days`, and filter `stage_df["occurred_at"] >=
cutoff` directly.
- Keep the human-readable span labels (`period.label`) and filename suffixes
(`period.key`) as today.
- Add tests: a calendar-anchored active-check test in
`tests/domain/test_recency.py` style, mirroring
`test_is_active_since_compares_timestamps_exactly`; tests in
`tests/analysis/test_role_coverage.py` and
`tests/analysis/test_team_activity.py` that supply a cutoff datetime and assert
`"active"`/`"quiet"` status, following the existing inline `datetime(...,
tzinfo=UTC)` and `_ev(...)` factory pattern. Confirm
`tests/contracts/test_output_contract.py` and
`tests/pipelines/test_difficulty.py` pick up the new period keys automatically,
and extend any assertion referencing a fixed set of period suffixes.

Phase 3: Verify frontend rendering and update fixtures

The frontend components need no production changes because they are data-driven. This phase updates the test fixtures and the one order-sensitive assertion so the new periods are exercised and the suite stays green.

Update frontend fixtures and the period-order assertion

Extend the test data to include the new periods and keep the ordering test correct.

• Update web/src/test/fixtures.ts. Add the new period keys (for example "182d" and "ytd") to a section's periods object and add their labels to period_labels, in the same shortest-first order the backend emits.
• Update web/src/test/app.test.tsx. Update the exact-array assertion in "offers the period windows shortest-first, with all time last" to include the new labels in the correct positions.
• Confirm PeriodTabs.tsx and SectionTable.tsx need no changes, because they render whatever keys the data provides.

🤖 Prompt for AI agents

Update the frontend test fixtures and the one order-sensitive test assertion to
cover the two new period keys. No production frontend code changes are required,
because `PeriodTabs.tsx` and `SectionTable.tsx` are data-driven and treat period
keys as opaque strings.

- In `web/src/test/fixtures.ts`: add the new period keys (`"182d"` and `"ytd"`)
to a section's `periods` object, and add their labels to `period_labels`, in the
same shortest-first order the backend emits.
- In `web/src/test/app.test.tsx`: update the exact-array assertion in the test
"offers the period windows shortest-first, with all time last" to include the
new labels in the correct positions.
- Confirm `PeriodTabs.tsx` and `SectionTable.tsx` require no changes, since they
render whatever keys the data provides.

Research

The period vocabulary is centralized in src/hiero_analytics/domain/periods.py. It defines a frozen Period dataclass (key, label, days: int | None, default) and a tuple ACTIVITY_PERIODS (7d, 30d, 365d). Every pipeline and the export layer iterate this tuple, so it is the single registry to extend. The frontend (web/src/components/PeriodTabs.tsx, SectionTable.tsx) is fully data-driven and treats period keys as opaque strings, so it needs no production code changes.

The current Period.cutoff(now) returns now - timedelta(days=self.days), which only expresses fixed rolling windows. domain/recency.py already defines two predicates: is_active(last_active, now, within_days) (day-count form, used everywhere) and is_active_since(last_active, cutoff) (cutoff form, currently unused). Several consumers pass period.days as an integer day count into is_active and into timedelta(days=...) arithmetic: pipelines/role_coverage.py, analysis/role_coverage.py, analysis/team_activity.py, pipelines/difficulty.py, pipelines/maintainer_pipeline.py, and their analysis modules. These are the seams that break for a calendar-anchored period, because "since start of year" has no fixed integer day count.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement changes to the period domain model and vocabulary so the dashboard can
express a calendar-anchored time range, then propagate this through the export
layer and tests.

- In `src/hiero_analytics/domain/periods.py`:
- Add an optional `anchor: str | None = None` field to the `Period` dataclass,
with the documented value `"year_start"`.
- Extend `Period.cutoff(now)` so that when `anchor == "year_start"`, it returns
January 1 of `now.year`, preserving `now`'s timezone. Keep the existing
rolling-window branch (`now - timedelta(days=self.days)`) and the all-time
branch (`None`) unchanged.
- Add an `is_all_time` property that returns `True` only when both `days is
None` and `anchor is None`.
- In `ACTIVITY_PERIODS`, insert `Period("182d", "6 months", 182)` between the
30d and 365d entries, and append `Period("ytd", "Since start of year",
anchor="year_start")` after the 365d entry. Keep `default=True` on the 30d entry
unchanged.
- In `src/hiero_analytics/export/data_api.py`, change the `API_PERIODS` filter
from `period.days is not None` to `not period.is_all_time`, so the `"ytd"`
period is still published. Do not change `_period_variants` or the manifest
`period_labels`. Confirm `export/macro_metrics.py` still resolves `"30d"` by key
without modification.
- In `tests/domain/test_periods.py`: extend the hardcoded vocabulary assertion
to include the `182d` and `ytd` entries in the correct order; add a test
asserting `Period("ytd", ..., anchor="year_start").cutoff(now)` returns January
1 of `now.year` with the correct timezone; add a test for `is_all_time` that
distinguishes the calendar-anchored period from a true all-time sentinel.
===============================================================================

Task: 2

Update the pipeline and analysis consumers that currently treat a period as a
fixed integer day count, so the calendar-anchored "since start of year" period
works correctly.

- In `src/hiero_analytics/analysis/role_coverage.py`: add an optional cutoff
parameter to `build_repo_role_coverage`, `find_unbadged_role_work`, and
`find_globally_quiet_role_holders`. When a cutoff is supplied, use
`is_active_since(last_active, cutoff)` to decide active/quiet status; otherwise
keep the existing `is_active(last_active, now, within_days)` path. Keep the
existing `int | None` day-count parameters and their
`ROLE_ACTIVE_DAYS`/`GONE_DARK_DAYS` defaults unchanged.
- In `src/hiero_analytics/analysis/team_activity.py`: add the same optional
cutoff parameter to `build_team_activity_summary` and its `_aggregate` helper,
using `is_active_since` when the cutoff is supplied.
- In `src/hiero_analytics/pipelines/role_coverage.py`: for each period, when
`period.days is None` (the calendar-anchored period), pass `period.cutoff(now)`
into the new cutoff parameters of `find_globally_quiet_role_holders`,
`build_repo_role_coverage` (via `_build_role_coverage`), and
`build_team_activity_summary`. Otherwise keep passing `period.days` as today. Do
not change the existing record pre-filtering, since it already uses
`period.cutoff(now)`.
- In `src/hiero_analytics/pipelines/difficulty.py`: build each span with
`period.cutoff(now)` instead of `period.days`, keeping `None` for the "All time"
span. Update `_run_window` to accept a `cutoff: datetime | None` and use it
directly (epoch or skip-filter when `None`) instead of computing `now -
timedelta(days=window_days)`.
- In `src/hiero_analytics/analysis/difficulty_analysis.py`: update only if its
`_run_window` callee still derives a cutoff from a day count; note that
`issues_labeled_since`/`issues_unlabeled_created_since` already accept a
`cutoff` datetime.
- In `src/hiero_analytics/pipelines/maintainer_pipeline.py`: build each span
with `period.cutoff(now)` and pass the cutoff into
`build_maintainer_repo_pipeline`.
- In `src/hiero_analytics/analysis/maintainer_pipeline.py`: change
`build_maintainer_repo_pipeline` to accept a cutoff datetime (or `None` for all
time) instead of `active_window_days`, and filter `stage_df["occurred_at"] >=
cutoff` directly.
- Keep the human-readable span labels (`period.label`) and filename suffixes
(`period.key`) as today.
- Add tests: a calendar-anchored active-check test in
`tests/domain/test_recency.py` style, mirroring
`test_is_active_since_compares_timestamps_exactly`; tests in
`tests/analysis/test_role_coverage.py` and
`tests/analysis/test_team_activity.py` that supply a cutoff datetime and assert
`"active"`/`"quiet"` status, following the existing inline `datetime(...,
tzinfo=UTC)` and `_ev(...)` factory pattern. Confirm
`tests/contracts/test_output_contract.py` and
`tests/pipelines/test_difficulty.py` pick up the new period keys automatically,
and extend any assertion referencing a fixed set of period suffixes.
===============================================================================

Task: 3

Update the frontend test fixtures and the one order-sensitive test assertion to
cover the two new period keys. No production frontend code changes are required,
because `PeriodTabs.tsx` and `SectionTable.tsx` are data-driven and treat period
keys as opaque strings.

- In `web/src/test/fixtures.ts`: add the new period keys (`"182d"` and `"ytd"`)
to a section's `periods` object, and add their labels to `period_labels`, in the
same shortest-first order the backend emits.
- In `web/src/test/app.test.tsx`: update the exact-array assertion in the test
"offers the period windows shortest-first, with all time last" to include the
new labels in the correct positions.
- Confirm `PeriodTabs.tsx` and `SectionTable.tsx` require no changes, since they
render whatever keys the data provides.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[5affron]

/assign

[exploreriii]

Hi @5affron please finish the other issues first

[phillip-nyinomujuni]

/assign

[Lemeri123]

can I take this on @exploreriii

[exploreriii]

Sorry, closing issue as had a front end revamp and no longer relevant