feat: detect last_changed/last_updated duration math and suggest for: field (#1157)

[SealKan]

What does this PR do?

Closes #1157 (partial — covers the best-practice detector for now() - X.last_changed/last_updated patterns).

HA 2026.5 introduced the native for: field on state triggers and conditions for duration-based checks. This PR adds a detector in best_practice_checker.py that catches automations still using the old template approach (now() - X.last_changed/last_updated) and suggests the native for: alternative.

Changes:

• best_practice_checker.py: New _RE_DURATION_MATH regex (two alternations: now() - X.last_changed and X.last_changed < now(); both require a dotted qualifier so bare Jinja variables named last_changed are not falsely flagged). Warning fires in both _check_template_string (conditions) and _check_triggers (template trigger value_template). Warning text includes a concrete platform: state, for: {minutes: N} example and links to automation-patterns.md#native-conditions / automation-patterns.md#trigger-types.
• test_best_practice_checker.py: 8 new tests covering condition last_changed, condition last_updated, trigger template, clean positive case (for: field — no warning), skill-ref presence, no generic double-flag, trigger warning uses #trigger-types anchor, and no false positive on bare last_changed Jinja variable.

Out of scope (per issue scope guidance):

• Docstring updates to ha_config_set_automation / ha_config_set_script — separate PR once the skill content is updated upstream
• Skills repo update (automation-patterns.md) — separate PR to homeassistant-ai/skills
• Template function metadata exposure — open design question in the issue

Type of change

• 🐛 Bug fix
• ✨ New feature
• 📚 Documentation
• 🔧 Maintenance/refactor
• 🧪 Tests only
• 💥 Breaking change

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest)
• Code follows style guidelines (uv run ruff check)

98 unit tests pass (was 90; 8 new). Ruff and mypy clean.

Future improvements

• Reverse comparison states.sensor.x.last_changed < now() - timedelta(...) is not caught by the current regex (the < alternation only covers X.last_changed < now() with nothing following). This is a rare HA pattern; it could be added as a third alternation if it shows up in practice.
• The numeric_state trigger also supports a for: field for similar duration checks; a separate detector could be added later.

Checklist

• I have updated documentation if needed

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new best practice check to help users migrate from template-based duration arithmetic to the native for: field introduced in Home Assistant 2026.5. By detecting patterns like now() - X.last_changed, the system now provides actionable guidance to improve automation performance and reliability by leveraging event-driven native conditions.

Highlights

• New Best Practice Detector: Added a regex-based detector to identify template-based duration checks (now() - X.last_changed/updated) in automations.
• Native 'for:' Suggestion: Updated the best practice checker to suggest using the native for: field on state triggers and conditions, which is more efficient and event-driven.
• Comprehensive Testing: Added 6 new unit tests to verify the detector's accuracy, ensure correct warning messages, and confirm that the native for: field does not trigger false positives.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new best practice check to the best_practice_checker.py tool, specifically targeting inefficient duration and recency calculations in Jinja templates (e.g., now() - last_changed). It suggests using Home Assistant's native for: field instead, which is more efficient and event-driven. Accompanying unit tests verify the detection logic across conditions and triggers. Feedback from the review highlights the need to refine the regex to ensure consistency and prevent false positives, as well as expanding the trigger check to cover other platforms like numeric_state that also support value_template.

[Patch76]

RfR? I'd do some review, if you're done (for the moment).

[kingpanther13]

@SealKan please mark as ready for review if you're done working on this so we can do a formal review on it

[kingpanther13]

@SealKan can you give an update on this and your other PR please? I'm just trying to keep the pipeline moving forward.

[SealKan]

Apologies for the delay. The two gemini items were addressed in prior commits (c6a46e2 tightens the regex to require a dotted qualifier on both alternations to prevent false positives, 824d120 extends the detector to numeric_state value_template). Just pushed a ruff format fix so CI should go green. Marking ready for review now.

[SealKan]

@Patch76 following up on the Area 3 row in your May 22 status map: the Ruff Lint failure is resolved — pushed a ruff format pass over best_practice_checker.py and its test. All checks are green now, the branch is rebased on master, and the Gemini review threads are resolved, so this is no longer a draft-state item.

Per your net, that should leave only the Area 4 decision before #1157 can close — happy to defer to whatever you and the maintainers land on there. The scripts choose-block for: gap you flagged is a small docstring addition I can fold into this PR or a separate follow-up, your call.

[Patch76]

Thanks for this — the detection is well-targeted, and the test suite is genuinely thorough: condition + trigger contexts, the for:-already-present negative case, generic-fallback suppression, and the bare-variable false-positive guard. The regex comment matches the pattern, the warning text is accurate, and both skill-doc anchors (#native-conditions, #trigger-types) resolve.

One item before merge:

The reversed comparison form is matched and documented, but never positively tested. _RE_DURATION_MATH has two alternations:

now() - X.last_changed/last_updated      # forward — well covered
X.last_changed/last_updated < now()      # reversed — no positive test

Every positive test uses the forward form; the reversed form's only appearance is the bare variable in test_no_false_positive_bare_last_changed_variable (asserted not flagged). So the reversed alternation with a dotted qualifier — the case it exists to catch — ships without a regression guard, and a later refactor could drop it silently. Could you add one positive test per context, e.g.:

"{{ states.binary_sensor.motion.last_changed < now() }}"                 # condition → expect warning
"{{ states.sensor.temp.last_updated < now() - timedelta(minutes=5) }}"   # trigger value_template → expect warning

One optional, non-blocking note: the duration assertions match on substring (any warning containing the fragments), so asserting exactly one such warning fires would also catch accidental double-flagging.

The reversed-form tests are the only blocker here; the rest is solid.

[SealKan]

Good catch @Patch76 - you're right, the reversed form had no positive coverage. Added one test per context (condition + trigger value_template) for the dotted-qualifier X.last_changed/last_updated < now() case in 5177d96. I also took your double-flagging note and asserted exactly one duration warning fires in each, rather than just "a warning containing the fragments", so an accidental double-flag would now fail too. Both forward and reversed alternations are guarded now.

[Patch76]

Thanks for this — the detector is clean and the test coverage is genuinely thorough (both attributes, both regex alternations, the numeric_state path, the bare-last_changed false-positive guard, and double-flag suppression are all covered). The condition→#native-conditions / trigger→#trigger-types anchor split is correct and explicitly tested. None of the following are blockers.

1. PR description is out of date — the reversed form is caught.
The "Future improvements" note says states.sensor.x.last_changed < now() - timedelta(...) isn't matched by the current regex. It actually is: the second alternation (?:\w+\.)+last_(?:changed|updated)\s*<\s*now\(\) matches X.last_changed < now() and doesn't care what follows now(), so the offset form matches too. Your own test_trigger_reversed_comparison_last_updated_math and test_condition_reversed_comparison_last_changed_math confirm this. Worth deleting that bullet so the description doesn't contradict the tests.

2. numeric_state path has no anchor assertion.
test_numeric_state_trigger_value_template_duration_math asserts on the message text ("last_changed/last_updated", "for:") but not on the #trigger-types anchor, so a copy-paste slip to #native-conditions in the numeric_state block (best_practice_checker.py ~L549) wouldn't be caught — unlike the template-trigger path, which has test_trigger_warning_uses_trigger_types_anchor. A one-line addition mirroring that test (run with skill_prefix=SKILL_PREFIX, assert automation-patterns.md#trigger-types) closes the gap.

3. Nit — regex comment wording.
best_practice_checker.py:81 says "at least one dotted qualifier". (?:\w+\.)+ is one-or-more, so trigger.last_changed (one dot) and states.sensor.x.last_changed (three) both match. "one or more dotted qualifiers" reads more precisely. Trivial.

For the record: I checked the new regex for ReDoS. It's technically O(n²) on a pathological all-dots input (a property it shares with the other dotted-path regexes in this file), but at realistic template depths it stays well under a millisecond, so there's nothing to do here.

[Patch76]

The reversed-comparison regression tests I asked for are now in place — test_condition_reversed_comparison_last_changed_math and test_trigger_reversed_comparison_last_updated_math, both asserting exactly one warning fires, which also closes the double-flag concern. That was the only blocker, so I am approving.

The three items in my companion comment (the stale "Future improvements" bullet, the missing #trigger-types anchor assertion on the numeric_state test, and the comment-wording nit) are all non-blocking — nice to fold in while you are here, but none gate merge. Thanks for the thorough tests.

[github-actions]

🧪 Your changes are now in the dev channel!

Your PR has been merged to master and is available for testing in the dev channel.

Test your changes before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

Found an issue? Please open a new bug report and mention this PR for context.