diff --git a/docs/worklogs/2026-01-02-agent-update-tests-and-bug-fix.md b/docs/worklogs/2026-01-02-agent-update-tests-and-bug-fix.md
new file mode 100644
index 0000000..ade8ff9
--- /dev/null
+++ b/docs/worklogs/2026-01-02-agent-update-tests-and-bug-fix.md
@@ -0,0 +1,172 @@
+---
+title: "Agent File Update Tests and Section Ordering Bug Fix"
+date: 2026-01-02
+keywords: [testing, bash, agent-context, bug-fix, state-machine, specify]
+commits: 1
+compression_status: uncompressed
+---
+
+# Session Summary
+
+**Date:** 2026-01-02
+**Focus Area:** Add comprehensive tests for agent file update logic and fix discovered bug
+
+# Accomplishments
+
+- [x] Created test-agent-update.sh with 33 test cases
+- [x] Discovered and fixed bug in update-agent-context.sh section ordering
+- [x] Tests cover: basic functionality, missing sections, timestamps, idempotency, change limits, DB entries, placement, edge cases
+- [x] Closed skills-hgm (Add tests for agent file update logic)
+- [x] Previous session: Completed skills-x33 (branch name tests - 27 tests)
+
+# Key Decisions
+
+## Decision 1: Test extraction approach using awk instead of sed
+
+- **Context:** Need to extract functions from update-agent-context.sh for isolated testing
+- **Options considered:**
+  1. `sed -n '/^function()/,/^}$/p'` - Original approach
+  2. `awk '/^function\(\)/,/^}$/ {print; if (/^}$/) exit}'` - More precise
+  3. Source entire script with mocked dependencies
+- **Rationale:** awk with explicit exit on closing brace is more reliable for multi-function scripts
+- **Impact:** Clean function extraction without pulling in adjacent functions
+
+## Decision 2: Fix the bug rather than document as expected behavior
+
+- **Context:** Found that Recent Changes section was silently skipped when preceded by Active Technologies
+- **Rationale:** This was clearly unintended behavior - the code was supposed to update both sections
+- **Impact:** Agent context files now correctly receive change entries regardless of section ordering
+
+# Problems & Solutions
+
+| Problem | Solution | Learning |
+|---------|----------|----------|
+| eval/sed extraction didn't work correctly for update_existing_agent_file | Used awk with explicit exit on `^}$` pattern | awk is more precise for function boundary detection |
+| Tests failing: change entries not added to existing Recent Changes | Traced through code, found `## Recent Changes` caught by generic "close tech section on any ##" logic | State machine section handlers must check specific headers before generic patterns |
+| Idempotency test counting wrong pattern | Pattern "Python + Django" appeared in both tech and change sections | Use anchored regex `^- pattern$` for specific line matching |
+
+# Technical Details
+
+## Code Changes
+
+- Total files modified: 2
+- Key files changed:
+  - `.specify/scripts/bash/update-agent-context.sh` - Fixed section ordering in while loop
+  - `.specify/scripts/bash/tests/test-agent-update.sh` - New test file (33 tests)
+
+## The Bug
+
+The `update_existing_agent_file` function processes files line-by-line with a state machine. When in the Active Technologies section (`in_tech_section=true`), encountering any `##` header would:
+
+1. Add pending tech entries
+2. Echo the header line
+3. Set `in_tech_section=false`
+4. **Continue to next iteration** ← Bug here!
+
+This meant `## Recent Changes` was echoed but the change entry addition code (which checks `if [[ "$line" == "## Recent Changes" ]]`) was never reached.
+
+**Fix:** Check for `## Recent Changes` BEFORE the generic "any ## closes tech section" logic:
+
+```bash
+# Handle Recent Changes section FIRST (before generic ## handling)
+if [[ "$line" == "## Recent Changes" ]]; then
+    # Close tech section if we were in it
+    if [[ $in_tech_section == true ]]; then
+        if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+            printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+            tech_entries_added=true
+        fi
+        in_tech_section=false
+    fi
+    echo "$line" >> "$temp_file"
+    # Add new change entry right after the heading
+    if [[ -n "$new_change_entry" ]]; then
+        echo "$new_change_entry" >> "$temp_file"
+    fi
+    ...
+fi
+```
+
+## Test Categories
+
+1. **Basic Functionality** (4 tests) - Tech/change entries added, existing content preserved
+2. **Missing Sections** (6 tests) - Creates sections when absent
+3. **Timestamp Updates** (2 tests) - Updates `**Last updated**:` dates
+4. **Idempotency** (1 test) - No duplicates when re-running
+5. **Change Entry Limits** (5 tests) - Max 2 existing changes kept
+6. **Database Entries** (3 tests) - DB-only additions work
+7. **Tech Entry Placement** (3 tests) - Entries at correct position
+8. **Edge Cases** (5 tests) - Empty, NEEDS CLARIFICATION, EOF handling
+9. **format_technology_stack** (4 tests) - Helper function unit tests
+
+## Commands Used
+
+```bash
+# Run the tests
+bash .specify/scripts/bash/tests/test-agent-update.sh
+
+# Debug function extraction
+eval "$(awk '/^update_existing_agent_file\(\)/,/^}$/ {print; if (/^}$/) exit}' script.sh)"
+
+# Trace execution
+bash -x -c '...'
+```
+
+# Process and Workflow
+
+## What Worked Well
+
+- Test-first debugging: Writing tests exposed the bug immediately
+- Incremental tracing: Adding debug output to narrow down the issue
+- Hypothesis testing: Created minimal test cases to verify the bug cause
+
+## What Was Challenging
+
+- Function extraction: eval/sed patterns are finicky with nested braces
+- Understanding state machine flow: Had to trace through manually to find where `continue` was short-circuiting
+
+# Learning and Insights
+
+## Technical Insights
+
+- Bash state machines need careful ordering: specific cases before generic patterns
+- `continue` in while loops can silently skip subsequent handlers
+- Test fixtures with `setup_test_file()` using heredocs are clean for bash testing
+- grep patterns for line counting need anchoring to avoid false positives
+
+## Process Insights
+
+- When tests fail unexpectedly, the code might be buggy (not just the tests)
+- Adding debug output (`echo "DEBUG: ..." >&2`) is fast way to trace bash
+
+# Context for Future Work
+
+## Open Questions
+
+- Should we add more tests for create_new_agent_file function?
+- Consider shellcheck/shfmt for the test files?
+
+## Next Steps
+
+- skills-s92: Add tests for deploy-skill.sh (continues testing theme)
+- skills-7bu: Add atomic file operations (related to file update code)
+- Rebuild home-manager to deploy updated script
+
+## Related Work
+
+- [2026-01-01-ops-review-phase-3-and-worklog-migration.md](2026-01-01-ops-review-phase-3-and-worklog-migration.md) - Previous session
+- skills-x33: Branch name tests (27 tests, completed in prior session)
+
+# Raw Notes
+
+- The deployed worklog skill still uses .org format; repo has .md
+- Network issue prevented bd sync (192.168.1.108:3000 unreachable)
+- Total test count across both test files: 60 tests (27 branch + 33 agent)
+
+# Session Metrics
+
+- Commits made: 1
+- Files touched: 2
+- Lines added/removed: +536/-13
+- Tests added: 33
+- Tests passing: 33/33