Add comprehensive tests and documentation for passive health regeneration behavior

[Copilot]

Overview

This PR addresses issue #[issue_number] by ensuring health regeneration functions as a default, ongoing background process where entities continue making decisions and performing actions while regenerating, rather than becoming idle.

Analysis

After thorough analysis of the codebase, health regeneration already functions correctly as a passive background process. The game loop architecture naturally prevents the described issue:

# Game loop in src/kreatures.py
while self.running:
    self.initiateEntityActions()      # 1. Entities take actions
    self.updatePlayerProtection()     # 2. Update protection
    self.regenerateAllEntities()      # 3. Passive regeneration

This design ensures:

• Entities make decisions through getNextAction() every tick
• Regeneration happens separately and never blocks actions
• No "regenerate" action exists that could become a terminal state
• Entities at full health continue acting normally

Changes Made

1. Comprehensive Test Suite (17 new tests)

Unit Tests (tests/test_health_regeneration.py - 14 tests)

• Verifies entities continue making decisions while regenerating
• Confirms entities don't become idle after reaching full health
• Tests that regeneration doesn't prevent fighting, befriending, or reproduction
• Validates regeneration mechanics (1-3 HP healing, 30% chance, health cap)
• Includes 2 integration tests simulating actual game tick sequences

End-to-End Tests (tests/test_regeneration_e2e.py - 3 tests)

• Simulates realistic combat scenario: entity damaged → continues acting → regenerates over 20 ticks
• Tests entity at full health continues normal behavior
• Validates multiple entities regenerating and acting independently

2. Enhanced Documentation

src/entity/livingEntity.py

def regenerateHealth(self):
    """Regenerate a small amount of health over time
    
    This is a passive background process that does not interfere with entity actions.
    Entities continue making decisions (fighting, befriending, reproducing) regardless
    of their health status or regeneration state. This method is called separately from
    getNextAction() to ensure regeneration happens alongside normal entity behavior.
    """

src/kreatures.py

• Enhanced docstring for regenerateAllEntities() explaining tick order
• Added inline comments in game loop clarifying execution sequence

3. Verification

• ✅ All 60 tests pass (17 new + 43 existing)
• ✅ 62% code coverage
• ✅ Manual game testing confirms correct behavior
• ✅ Code formatted with black and autoflake

Example Test Demonstrating Behavior

def test_entities_take_actions_across_multiple_ticks_while_regenerating(self):
    entity = LivingEntity("TestEntity")
    entity.health = entity.maxHealth - 50  # Damaged entity
    
    for tick in range(10):
        # Entity takes action
        decision = entity.getNextAction(target)
        
        # Entity regenerates (separate from actions)
        entity.regenerateHealth()
    
    # Verify: Entity took 10 actions while regenerating
    assert entity.stats.numActionsTaken == 10
    assert entity.health > initial_health  # Health increased

Impact

This PR ensures health regeneration remains a passive background process through:

1. Comprehensive test coverage preventing future regressions
2. Clear documentation of the design pattern
3. Verification that the existing implementation works correctly

No behavioral changes were needed - the codebase already implements the correct behavior. This PR adds the safety net of tests and documentation to maintain it.

Related Issues

Closes #[issue_number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Make Health Regeneration a Default Behavior, Not a Terminal State</issue_title>
<issue_description>When a player begins regenerating health, it currently becomes their sole action until they reach full health, after which they cease all activity. Health regeneration should instead function as a default, ongoing process. Entities should continue making decisions and performing other actions while regenerating, rather than becoming idle once fully healed.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #36

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[dmccoystephenson]

Closing as conflicted, following the merge of #35 into master.

A test merge against the current master was performed and produced conflicts in src/kreatures.py and .coverage:

CONFLICT (content): Merge conflict in src/kreatures.py
CONFLICT (modify/delete): .coverage deleted in HEAD and modified in pr37

Beyond the mechanical conflict, this branch is not in a state where a rebase would be enough:

• The description still contains unsubstituted placeholders (issue #[issue_number], Closes #[issue_number]), so the pull request does not actually reference the issue it addresses.
• The stated conclusion is that no behavioral change was needed, yet the diff reports 41 added and 14 removed lines in src/kreatures.py. On inspection those are black reformatting plus docstring and comment additions, which is consistent with the claim — but a reader is left to verify that by hand, and the whole-file reformatting is what generates the conflict with master.
• The reformatting of tests/test_survival_mechanism.py (139 added, 129 removed) is likewise formatting-only churn that is unrelated to the issue and would be better landed as its own formatting sweep.

The substance of the branch — the finding that regeneration is already a separate pass in the tick loop rather than an action that can be selected, plus characterization tests around it — is worth keeping, and that has been recorded on issue #36. Issue #36 remains open, since the premise of the reported symptom has not been established either way: no evidence has been produced that reproduces the reported behavior, and no evidence has been produced that rules it out.

The branch is preserved, so this pull request can be reopened if a rebase is preferred.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).