feat: Add conditional sections support ({{#if}} blocks) - Phase 2

[randlee]

Summary

Implements conditional sections for MDTool, enabling single templates to target multiple roles/scenarios (e.g., QA-TEST vs QA-REPORT agents) using {{#if EXPR}}...{{else}}...{{/if}} syntax.

Release: v1.1.0
Branch: feature/conditionals → main
Sprint Status: Wave 1 ✅ Complete | Wave 2 🔄 In Progress | Wave 3 ⏳ Pending

---

Waves Overview

Wave 1: Core Conditionals Logic ✅ COMPLETE

Files: 5 Core classes + 36 unit tests
Status: All 388 tests passing (352 existing + 36 new), zero regressions

Delivered:

• IArgsAccessor - Case-insensitive, dot-path variable access interface
• ArgsJsonAccessor - JsonDocument-backed implementation
• ConditionalEvaluator - Expression parser and evaluator with:
  • Operators: ==, !=, &&, ||, !, ()
  • Functions: contains, startsWith, endsWith, in, exists
  • Tag scanner: {{#if}}, {{else if}}, {{else}}, {{/if}}
  • Code fence protection (skips tags inside ``` blocks)
  • Type-aware comparisons (string, number, boolean)
  • Nesting limit enforcement (configurable, default: 10)
• ConditionalOptions - Configuration (Strict, CaseSensitiveStrings, MaxNesting)
• ConditionalTrace - Debugging trace output structures

Test Coverage: 36 comprehensive tests covering expression parsing, tag matching, code fences, case modes, type awareness, nesting, and error handling.

---

Wave 2: Command Integration 🔄 IN PROGRESS

Target: ~20 integration tests, 408+ total tests

Planned:

• Add --enable-conditions flag (opt-in, disabled by default)
• Add --strict-conditions, --conditions-trace-out, --conditions-max-depth options
• ProcessCommand integration: evaluate conditionals before substitution
• ValidateCommand integration: content-scoped validation (only require vars in kept branches)
• Integration tests for role-based content, code fence protection, trace output

---

Wave 3: Documentation & Examples ⏳ PENDING

Target: ~5 example tests, 412+ total tests

Planned:

• Update design docs (Core.md, Commands.md)
• Update README with conditional sections guide
• Create examples (conditionals.md with TEST/REPORT roles)
• Example validation tests

---

Key Features

Expression Support

{{#if ROLE == 'TEST'}}
  Run unit tests
{{else if ROLE == 'REPORT'}}
  Generate quality report
{{else}}
  No-op
{{/if}}

Functions

• ROLE.Contains('TEST') - Substring matching
• AGENT.StartsWith('QA') - Prefix matching
• in(ROLE, ['TEST', 'REPORT']) - Array membership
• exists(OPTIONAL_VAR) - Variable presence check

Processing Order

1. Load args + merge YAML defaults
2. Evaluate conditionals → effective content
3. Extract variables from effective content
4. Substitute variables
5. Output result

---

Quality Gates

Wave 1: ✅ PASSED

• All 352 existing tests passing (zero regressions)
• All 36 new tests passing
• Total: 388/388 tests (100% pass rate)
• Build: 0 errors, 0 warnings

Wave 2: 🔄 In Progress

• Target: 408+ tests (100% pass rate)
• Zero regression requirement maintained

Wave 3: ⏳ Pending

• Target: 412+ tests (100% pass rate)
• All documentation complete

---

Design Decisions

• Opt-in: Disabled by default in v1.1.0 (requires --enable-conditions flag)
• Code fence protection: Tags inside ``` blocks treated as literal by default
• Content-scoped validation: Only variables in kept branches are required
• Type-aware: No implicit type coercion (string != number)
• Case-insensitive: Variable lookup and string comparisons (unless --strict-conditions)

---

Test Plan

• Wave 1: Core logic unit tests (36 tests)
• Wave 2: Command integration tests (~20 tests)
• Wave 3: Example validation tests (~5 tests)
• Final: Full regression suite (412+ tests, 100% pass rate)

---

Documentation

Design Specs:

• docs/design/Conditionals.md - Full specification
• docs/conditionals-sprint-plan.md - Sprint execution plan

Updated (Wave 3):

• docs/design/Core.md - ConditionalEvaluator section
• docs/design/Commands.md - CLI options documentation
• README.md - User guide and examples

---

References

Related Issues: Conditionals Sprint (Phase 2)
Design Doc: docs/design/Conditionals.md
Sprint Plan: docs/conditionals-sprint-plan.md
Base Branch: main (352 tests passing)
Target Merge: After all 3 waves complete + QA approval

---

🤖 Generated with Claude Code

[github-actions]

✅ Unit tests completed. Check the Actions tab for detailed results.

[github-actions]

✅ Unit tests completed. Check the Actions tab for detailed results.

[github-actions]

✅ Unit tests completed. Check the Actions tab for detailed results.

[github-actions]

✅ Unit tests completed. Check the Actions tab for detailed results.

[github-actions]

✅ Unit tests completed. Check the Actions tab for detailed results.

[github-actions]

✅ Unit tests completed. Check the Actions tab for detailed results.