Implement contact-card YAML front matter parser/serializer

[Chris0Jeky]

Summary

• Adds ContactCardFrontMatter DTO modeling structured contact fields (name, handles, tags, status, cadence, etc.) stored as YAML front matter in card descriptions for the card-first Outreach CRM (issue OUT-02: Implement contact-card YAML front matter parser/serializer contract #264, Wave 2 foundation)
• Adds ContactCardYamlParser static utility with Parse and Serialize methods: extracts ----delimited YAML front matter, deserializes via YamlDotNet with underscore naming convention, validates type/tier/status enums, and returns explicit error lists instead of throwing
• Round-trip safety: Parse(Serialize(fm, body)) produces identical output
• Graceful degradation: malformed YAML, missing closing delimiter, invalid field values all return structured errors without crashing
• 38 unit tests covering round-trip stability, edge cases (null/empty input, no front matter, Windows line endings, Unicode, special characters, unknown fields, trailing whitespace), validation, and serializer behavior

Closes #264

Test plan

• All 38 new ContactCardYamlParserTests pass
• Full backend test suite passes (1,012 Application + 407 Api + 218 Domain + 8 Architecture + 4 CLI = all green)
• Round-trip test verifies Serialize -> Parse -> Serialize stability
• Edge cases: null, empty, plain text, no delimiters, unclosed delimiter, empty YAML block, invalid YAML syntax
• Validation: invalid type, invalid relationship_tier, invalid status, multiple simultaneous errors
• Encoding: Windows line endings (\r\n), Unicode display names, special characters in notes
• Serializer: null field omission, underscore naming convention, ArgumentNullException on null input

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[gemini-code-assist]

Code Review

This pull request introduces a YAML front matter parser and serializer for contact cards, enabling structured metadata storage within card descriptions. It includes the ContactCardFrontMatter DTO, the ContactCardYamlParser service, and a comprehensive suite of unit tests. The feedback focuses on improving performance by caching static resources like serializers and validation sets, enhancing data integrity through date format validation, and simplifying test assertions using object equivalency.

[gemini-code-assist]

The Validate method is missing validation for LastTouchAt and NextTouchAt properties. This could allow invalid date formats to be saved, potentially causing parsing errors later. Please add validation to ensure these fields, if present, are valid ISO 8601 date strings (e.g., "YYYY-MM-DD").

You can use DateOnly.TryParse() for this before returning the errors. For example:

if (!string.IsNullOrEmpty(fm.LastTouchAt) && !DateOnly.TryParse(fm.LastTouchAt, out _))
{
    errors.Add($"Invalid last_touch_at format '{fm.LastTouchAt}'. Expected ISO 8601 date (YYYY-MM-DD).");
}
// and similarly for NextTouchAt

[gemini-code-assist]

The validTiers and validStatuses HashSets are re-created on every call to Validate. For better performance and to adhere to best practices, these should be defined once as static readonly fields within the ContactCardYamlParser class.

You can add these fields to ContactCardYamlParser:

private static readonly HashSet<string> ValidTiers = new(StringComparer.OrdinalIgnoreCase) { "A", "B", "C" };
private static readonly HashSet<string> ValidStatuses = new(StringComparer.OrdinalIgnoreCase)
{
    "cold", "warm", "active", "referral", "interviewing", "closed"
};

Then, the validation logic can be simplified as suggested.

        if (!string.IsNullOrEmpty(fm.RelationshipTier) && !ValidTiers.Contains(fm.RelationshipTier))
        {
            errors.Add($"Invalid relationship_tier '{fm.RelationshipTier}'. Expected one of: A, B, C.");
        }

        if (!string.IsNullOrEmpty(fm.Status) && !ValidStatuses.Contains(fm.Status))
        {
            errors.Add($"Invalid status '{fm.Status}'. Expected one of: cold, warm, active, referral, interviewing, closed.");
        }

[gemini-code-assist]

The IDeserializer and ISerializer instances are built on every call to Parse and Serialize respectively. Since their configuration is constant, they can be created once and stored in static readonly fields for improved performance.

You can define them at the class level:

private static readonly IDeserializer Deserializer = new DeserializerBuilder()
    .WithNamingConvention(UnderscoredNamingConvention.Instance)
    .IgnoreUnmatchedProperties()
    .Build();

private static readonly ISerializer Serializer = new SerializerBuilder()
    .WithNamingConvention(UnderscoredNamingConvention.Instance)
    .ConfigureDefaultValuesHandling(DefaultValuesHandling.OmitNull)
    .Build();

Then, you can use these fields directly in Parse and Serialize and remove the BuildDeserializer() and BuildSerializer() methods.

[gemini-code-assist]

Instead of asserting each property individually, you can use FluentAssertions' BeEquivalentTo to compare the deserialized FrontMatter object with the original one. This makes the test more concise and easier to maintain.

        result.Errors.Should().BeEmpty();
        result.FrontMatter.Should().BeEquivalentTo(original);
        result.Body.Should().Be(body);

[gemini-code-assist]

Similar to the full contact round-trip test, you can use BeEquivalentTo to simplify the assertions here. This makes the test more concise and robust.

        result.Errors.Should().BeEmpty();
        result.FrontMatter.Should().BeEquivalentTo(original);
        result.Body.Should().BeEmpty();

[Chris0Jeky]

Adversarial Self-Review

YAML injection / security

• No risk: YamlDotNet does not support arbitrary code execution tags (unlike Python's PyYAML with !!python/exec). The deserializer uses IgnoreUnmatchedProperties() so unexpected fields are silently dropped without side effects.
• Validation error messages include user-supplied values (e.g. Invalid status 'X'). These are safe for internal use but callers should be aware when surfacing to external UI.

Encoding

• Line ending normalization: ExtractFrontMatterBlock normalizes \r\n and \r to \n. This means the body is returned with \n endings even if the input had \r\n. The Serializer also uses \n. This is intentional and consistent: round-trip Serialize -> Parse -> Serialize is stable, but parsing externally-authored content with \r\n in the body will normalize those endings. Acceptable for the card-first use case.

Round-trip safety

• Verified: Serialize(fm, body) -> Parse -> Serialize produces identical output (tested in RoundTrip_FullContact_ProducesIdenticalOutput).
• Field ordering: YamlDotNet serializes in property-declaration order, so round-trip is deterministic. However, if a user hand-edits YAML with a different field order, parsing succeeds but re-serialization will reorder fields. This is expected and documented by convention.

Edge cases covered

• Null/empty input, plain text (no delimiters), delimiters not at start, unclosed delimiter, empty YAML block, invalid YAML syntax, unknown fields, trailing whitespace on delimiters, multiple --- lines in body, no body after closing delimiter, Windows line endings, Unicode, special characters, quoted values, empty collections.

Issues found and fixed

1. Allocation waste (fixed in ba73235): BuildDeserializer() and BuildSerializer() created new YamlDotNet builder instances on every call. Validation HashSets were also reallocated per call. Refactored to static readonly fields. YamlDotNet's ISerializer/IDeserializer are thread-safe after construction.

Remaining notes (not bugs)

• ContactCardFrontMatter.Type defaults to "contact" (non-null), so it is always serialized. An empty-string Type would pass validation (only non-empty non-"contact" values are flagged) but serialize as type: "". This is edge-case-only and harmless.
• No size limit on the YAML block or body. For card descriptions this is fine, but if this parser is ever used on untrusted external input, a max-size guard should be added.

[Chris0Jeky]

Fixes applied

Merge conflicts resolved — rebased/merged with current main.

Gemini HIGH — Date validation added (ContactCardYamlParser.Validate):

• last_touch_at and next_touch_at now validated as ISO 8601 date strings (YYYY-MM-DD) using DateOnly.TryParse()
• Invalid dates produce structured errors, consistent with existing type/tier/status validation
• 3 new test cases cover: invalid last_touch_at, invalid next_touch_at, valid date passes

Gemini MEDIUMs — Static caching (from self-review commit ba73235): already applied — IDeserializer, ISerializer, ValidTiers, ValidStatuses are all private static readonly.

Gemini MEDIUMs — Test simplification with BeEquivalentTo: keeping current test style for now as the assertions are explicit and easy to read; no functional gap.

[Chris0Jeky]

Merge conflict resolved

Taskdeck.Application.csproj and Taskdeck.Infrastructure.csproj: Resolved package reference conflict by combining both sides in both projects:

• Microsoft.IdentityModel.Tokens → 8.17.0 (from main — security upgrade)
• System.IdentityModel.Tokens.Jwt → 8.17.0 (from main — security upgrade)
• YamlDotNet → 16.3.0 (kept from PR — required for YAML parser)

The prior "Resolve merge conflicts" commit had left both projects at 7.7.1, causing a NU1605 version downgrade error. Both .csproj files now use 8.17.0 consistently.

Build: succeeded (0 warnings, 0 errors). ContactCardYamlParser tests: 41 passed.