Adopt bracketed format for Workday metadata fields

format_notes_field() now outputs bracketed format matching app.py's
export and the module's own documentation:
- [Performance Rating: X%]
- [Strengths: ...]
- [Improvements: ...]
- [Mentor: ...]
- [Mentees: ...]
- Section header Justification: (allows multi-line text)

Parser simplified to only accept the canonical bracketed format,
removing unnecessary dual-pattern matching that added complexity
for backward compatibility we don't need.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: adereis

AGENTS.md

@@ -93,6 +93,15 @@ Manager name parsed from: `"Supervisory Organization (Manager Name)"` or `"Direc
 
 **Overwritten on re-import** (from Workday): salary, bonus targets, org structure, management_level, country, tenure fields
 
+**Notes Field Format** (canonical bracketed format for Workday round-tripping):
+- `[Performance Rating: X%]`
+- `[Override: X%, reason]` (special cases like pro-rata leave)
+- `[Strengths: ...]` / `[Improvements: ...]`
+- `[Mentor: ...]` / `[Mentees: ...]`
+- `Justification:` (section header, allows multi-line text)
+
+Parser: `notes_parser.py` — `parse_notes_field()` extracts, `format_notes_field()` serializes. Exports use this format in the Notes column; the separate Description column is human-readable (no brackets).
+
 ### Talent Calibration
 
 **Routes**: `/calibrate` (UI), `/api/calibrate` (POST), `/api/calibrate/status` (GET), `/export/talent` (GET)

notes_parser.py

@@ -74,51 +74,41 @@ def parse_notes_field(notes_text: Optional[str]) -> dict:
     # Normalize line endings
     text = notes_text.replace('\r\n', '\n').replace('\r', '\n')
 
-    # Parse Performance Rating
-    rating_match = re.search(r'Performance\s+Rating:\s*([\d.]+)\s*%', text, re.IGNORECASE)
+    # Parse Performance Rating: [Performance Rating: X%]
+    rating_match = re.search(r'\[Performance\s+Rating:\s*([\d.]+)\s*%\]', text, re.IGNORECASE)
     if rating_match:
         try:
             result['performance_rating'] = float(rating_match.group(1))
         except ValueError:
             pass
 
-    # Parse Mentor (single person who mentored this employee)
-    # Supports both bracketed [Mentor: X] and non-bracketed Mentor: X formats
-    mentor_match = re.search(r'^\[Mentor:\s*([^\]]+)\]', text, re.MULTILINE | re.IGNORECASE)
-    if not mentor_match:
-        mentor_match = re.search(r'^Mentor:\s*(.+?)$', text, re.MULTILINE | re.IGNORECASE)
+    # Parse Mentor: [Mentor: X]
+    mentor_match = re.search(r'\[Mentor:\s*([^\]]+)\]', text, re.IGNORECASE)
     if mentor_match:
         mentor_value = mentor_match.group(1).strip()
         if mentor_value:
             result['mentors'] = mentor_value
 
-    # Parse Mentees (people this employee mentored)
-    mentees_match = re.search(r'^Mentees?:\s*(.+?)$', text, re.MULTILINE | re.IGNORECASE)
+    # Parse Mentees: [Mentees: X; Y]
+    mentees_match = re.search(r'\[Mentees?:\s*([^\]]+)\]', text, re.IGNORECASE)
     if mentees_match:
         mentees_value = mentees_match.group(1).strip()
         if mentees_value:
             result['mentees'] = mentees_value
 
-    # Parse Strengths
-    strengths_match = re.search(r'^Strengths?:\s*(.+?)$', text, re.MULTILINE | re.IGNORECASE)
+    # Parse Strengths: [Strengths: X; Y]
+    strengths_match = re.search(r'\[Strengths?:\s*([^\]]+)\]', text, re.IGNORECASE)
     if strengths_match:
         strengths_value = strengths_match.group(1).strip()
         if strengths_value:
             result['tenets_strengths'] = strengths_value
 
-    # Parse Areas for Improvement (various phrasings)
-    improvements_patterns = [
-        r'^Areas?\s+for\s+Improvement:\s*(.+?)$',
-        r'^Improvements?:\s*(.+?)$',
-        r'^Areas?\s+to\s+Improve:\s*(.+?)$',
-    ]
-    for pattern in improvements_patterns:
-        improvements_match = re.search(pattern, text, re.MULTILINE | re.IGNORECASE)
-        if improvements_match:
-            improvements_value = improvements_match.group(1).strip()
-            if improvements_value:
-                result['tenets_improvements'] = improvements_value
-            break
+    # Parse Improvements: [Improvements: X; Y]
+    improvements_match = re.search(r'\[Improvements?:\s*([^\]]+)\]', text, re.IGNORECASE)
+    if improvements_match:
+        improvements_value = improvements_match.group(1).strip()
+        if improvements_value:
+            result['tenets_improvements'] = improvements_value
 
     # [Override: 50%] or [Override: 50%, Paternity leave Apr-Sep]
     # Combined format: percentage required, reason optional after comma
@@ -182,11 +172,9 @@ def format_notes_field(
     """
     lines = []
 
+    # Bracketed fields (tool additions) - order matches app.py export
     if performance_rating is not None:
-        lines.append(f"Performance Rating: {performance_rating}%")
-
-    if justification:
-        lines.append(f"Justification: {justification}")
+        lines.append(f"[Performance Rating: {performance_rating}%]")
 
     # Special case override (pro-rata leave, retention, etc.)
     if bonus_override_percent is not None:
@@ -195,18 +183,24 @@ def format_notes_field(
         else:
             lines.append(f"[Override: {bonus_override_percent}%]")
 
+    if tenets_strengths:
+        lines.append(f"[Strengths: {tenets_strengths}]")
+
+    if tenets_improvements:
+        lines.append(f"[Improvements: {tenets_improvements}]")
+
     if mentor:
-        lines.append(f"Mentor: {mentor}")
+        lines.append(f"[Mentor: {mentor}]")
 
     if mentees:
         # Normalize to semicolon-separated for consistency with tenets
         normalized_mentees = '; '.join(m.strip() for m in mentees.replace(';', ',').split(',') if m.strip())
-        lines.append(f"Mentees: {normalized_mentees}")
-
-    if tenets_strengths:
-        lines.append(f"Strengths: {tenets_strengths}")
+        lines.append(f"[Mentees: {normalized_mentees}]")
 
-    if tenets_improvements:
-        lines.append(f"Areas for Improvement: {tenets_improvements}")
+    # Justification uses section header format (allows multi-line, any characters)
+    if justification:
+        lines.append('')  # Blank line before section
+        lines.append('Justification:')
+        lines.append(justification)
 
     return '\n'.join(lines)

scripts/generate-sample-xlsx.py

@@ -630,7 +630,7 @@ def generate_historical_notes(rating, include_full_details=True):
         if choice == 'empty':
             return ''
         elif choice == 'rating_only':
-            return f"Performance Rating: {rating}%"
+            return f"[Performance Rating: {rating}%]"
         else:
             return format_notes_field(
                 performance_rating=rating,

tests/test_import_api.py

@@ -157,7 +157,7 @@ def test_analyze_valid_xlsx(self, client, db_session):
                 'associate': 'John Doe',
                 'supervisory_organization': 'Engineering',
                 'current_job_profile': 'Senior Engineer',
-                'notes': 'Performance Rating: 125%\nJustification: Great work',
+                'notes': '[Performance Rating: 125%]\n\nJustification:\nGreat work',
                 'proposed_percent_of_target_bonus': 118.5
             },
             {
@@ -196,7 +196,7 @@ def test_analyze_historical_period_exists(self, client, db_session):
             {
                 'associate_id': 'EMP001',
                 'associate': 'John Doe',
-                'notes': 'Performance Rating: 125%'
+                'notes': '[Performance Rating: 125%]'
             }
         ]
 
@@ -587,7 +587,7 @@ def test_import_historical_creates_period_and_snapshots(self, client, db_session
                 'current_job_profile': 'Senior Engineer',
                 'bonus_target_manager_currency': 15000,
                 'proposed_percent_of_target_bonus': 118.5,
-                'notes': 'Performance Rating: 125%\nJustification: Excellent work\nMentor: Alice\nStrengths: Leadership'
+                'notes': '[Performance Rating: 125%]\n[Mentor: Alice]\n[Strengths: Leadership]\n\nJustification:\nExcellent work'
             },
             {
                 'associate_id': 'EMP002',
@@ -675,7 +675,7 @@ def test_import_historical_updates_existing_snapshots(self, client, db_session):
                 'associate': 'New Name',
                 'supervisory_organization': 'New Org',
                 'proposed_percent_of_target_bonus': 125.0,
-                'notes': 'Performance Rating: 130%\nJustification: Updated review'
+                'notes': '[Performance Rating: 130%]\n\nJustification:\nUpdated review'
             }
         ]
 
@@ -781,7 +781,7 @@ def test_parse_xlsx_employees(self, db_session):
                 'current_base_pay_manager_currency': 150000,
                 'bonus_target_manager_currency': 22500,
                 'proposed_percent_of_target_bonus': 118.5,
-                'notes': 'Performance Rating: 125%'
+                'notes': '[Performance Rating: 125%]'
             }
         ]
 
@@ -809,7 +809,7 @@ def test_parse_xlsx_employees(self, db_session):
             assert emp['current_base_pay_manager_currency'] == 150000
             assert emp['bonus_target_manager_currency'] == 22500
             assert emp['proposed_percent_of_target_bonus'] == 118.5
-            assert 'Performance Rating: 125%' in emp['notes']
+            assert '[Performance Rating: 125%]' in emp['notes']
             # Check that currency was extracted from headers
             assert metadata.get('currency') == 'USD'
         finally:

tests/test_notes_parser.py

@@ -11,12 +11,14 @@ class TestParseNotesField:
 
     def test_parse_complete_notes(self):
         """Test parsing a complete notes field with all fields."""
-        notes = """Performance Rating: 125.5%
-Justification: Great performance, delivered feature X, Y and Z. Role model to the team.
-Mentor: Alice Chen
-Mentees: Bob Jones, Carol White
-Strengths: Customer Obsession, Ownership, Bias for Action
-Areas for Improvement: Earn Trust, Dive Deep"""
+        notes = """[Performance Rating: 125.5%]
+[Strengths: Customer Obsession, Ownership, Bias for Action]
+[Improvements: Earn Trust, Dive Deep]
+[Mentor: Alice Chen]
+[Mentees: Bob Jones, Carol White]
+
+Justification:
+Great performance, delivered feature X, Y and Z. Role model to the team."""
 
         result = parse_notes_field(notes)
 
@@ -29,7 +31,7 @@ def test_parse_complete_notes(self):
 
     def test_parse_rating_only(self):
         """Test parsing notes with only performance rating."""
-        notes = "Performance Rating: 100%"
+        notes = "[Performance Rating: 100%]"
 
         result = parse_notes_field(notes)
 
@@ -42,11 +44,13 @@ def test_parse_rating_only(self):
 
     def test_parse_multiline_justification(self):
         """Test parsing multi-line justification text."""
-        notes = """Performance Rating: 130%
-Justification: This employee demonstrated exceptional performance.
+        notes = """[Performance Rating: 130%]
+[Mentor: Senior Dev]
+
+Justification:
+This employee demonstrated exceptional performance.
 They led the API redesign project which reduced latency by 40%.
-Additionally, they mentored two junior engineers.
-Mentor: Senior Dev"""
+Additionally, they mentored two junior engineers."""
 
         result = parse_notes_field(notes)
 
@@ -76,10 +80,12 @@ def test_parse_none_notes(self):
 
     def test_parse_case_insensitive(self):
         """Test that field names are case-insensitive."""
-        notes = """PERFORMANCE RATING: 110%
-justification: good work
-MENTOR: Boss
-strengths: Leadership"""
+        notes = """[PERFORMANCE RATING: 110%]
+[MENTOR: Boss]
+[STRENGTHS: Leadership]
+
+Justification:
+good work"""
 
         result = parse_notes_field(notes)
 
@@ -90,37 +96,28 @@ def test_parse_case_insensitive(self):
 
     def test_parse_rating_with_decimal(self):
         """Test parsing rating with decimal places."""
-        notes = "Performance Rating: 115.75%"
+        notes = "[Performance Rating: 115.75%]"
 
         result = parse_notes_field(notes)
 
         assert result['performance_rating'] == 115.75
 
     def test_parse_without_rating(self):
         """Test parsing notes without performance rating."""
-        notes = """Justification: Solid performance this period.
-Strengths: Teamwork, Communication"""
+        notes = """[Strengths: Teamwork, Communication]
+
+Justification:
+Solid performance this period."""
 
         result = parse_notes_field(notes)
 
         assert result['performance_rating'] is None
         assert result['justification'] == "Solid performance this period."
         assert result['tenets_strengths'] == "Teamwork, Communication"
 
-    def test_parse_alternate_improvement_phrasings(self):
-        """Test parsing various phrasings for improvements."""
-        notes1 = "Improvements: Time Management"
-        notes2 = "Areas to Improve: Focus"
-
-        result1 = parse_notes_field(notes1)
-        result2 = parse_notes_field(notes2)
-
-        assert result1['tenets_improvements'] == "Time Management"
-        assert result2['tenets_improvements'] == "Focus"
-
     def test_parse_windows_line_endings(self):
         """Test parsing notes with Windows line endings."""
-        notes = "Performance Rating: 100%\r\nJustification: Test\r\nMentor: Alice"
+        notes = "[Performance Rating: 100%]\r\n[Mentor: Alice]\r\n\r\nJustification:\r\nTest"
 
         result = parse_notes_field(notes)
 
@@ -130,12 +127,14 @@ def test_parse_windows_line_endings(self):
 
     def test_parse_real_world_example(self):
         """Test parsing a real-world example from the export page."""
-        notes = """Performance Rating: 155.0%
-Justification: Great performance, delivered feature X, Y and Z. Role model to the team.
-Mentor: Rhoda Map
-Mentees: Mai Stone
-Strengths: We Serve Our Customers, We Champion Ownership, We Start with Trust
-Areas for Improvement: We Embrace Transparency, We Navigate Change with Resilience"""
+        notes = """[Performance Rating: 155.0%]
+[Strengths: We Serve Our Customers, We Champion Ownership, We Start with Trust]
+[Improvements: We Embrace Transparency, We Navigate Change with Resilience]
+[Mentor: Rhoda Map]
+[Mentees: Mai Stone]
+
+Justification:
+Great performance, delivered feature X, Y and Z. Role model to the team."""
 
         result = parse_notes_field(notes)
 
@@ -161,12 +160,14 @@ def test_format_complete_notes(self):
             tenets_improvements="Communication"
         )
 
-        assert "Performance Rating: 125.0%" in result
-        assert "Justification: Great work this quarter." in result
-        assert "Mentor: Alice" in result
-        assert "Mentees: Bob; Carol" in result  # Normalized to semicolons
-        assert "Strengths: Leadership, Teamwork" in result
-        assert "Areas for Improvement: Communication" in result
+        assert "[Performance Rating: 125.0%]" in result
+        assert "[Mentor: Alice]" in result
+        assert "[Mentees: Bob; Carol]" in result  # Normalized to semicolons
+        assert "[Strengths: Leadership, Teamwork]" in result
+        assert "[Improvements: Communication]" in result
+        # Justification uses section header format
+        assert "Justification:" in result
+        assert "Great work this quarter." in result
 
     def test_format_partial_notes(self):
         """Test formatting with only some fields."""
@@ -175,10 +176,11 @@ def test_format_partial_notes(self):
             justification="Met expectations."
         )
 
-        assert "Performance Rating: 100.0%" in result
-        assert "Justification: Met expectations." in result
-        assert "Mentor:" not in result
-        assert "Strengths:" not in result
+        assert "[Performance Rating: 100.0%]" in result
+        assert "Justification:" in result
+        assert "Met expectations." in result
+        assert "[Mentor:" not in result
+        assert "[Strengths:" not in result
 
     def test_format_empty_notes(self):
         """Test formatting with no fields returns empty string."""
@@ -279,7 +281,7 @@ def test_format_with_override(self):
             justification="Pro-rata bonus"
         )
 
-        assert "Performance Rating: 100.0%" in result
+        assert "[Performance Rating: 100.0%]" in result
         assert "[Override: 50.0%, Paternity leave Apr-Sep]" in result
         assert "Justification:" in result
         assert "Pro-rata bonus" in result
@@ -303,7 +305,7 @@ def test_format_no_override(self):
         )
 
         assert "[Override:" not in result
-        assert "Performance Rating: 100.0%" in result
+        assert "[Performance Rating: 100.0%]" in result
 
     def test_override_roundtrip(self):
         """Test that formatting then parsing returns original override values."""