M2-5: Markdown-First Human Summaries

[akserg]

Goal

Make Markdown the primary human-facing representation of orchestrator activity, so users can understand what is happening without reading JSON.

This milestone ensures that every meaningful orchestrator action produces a clear, readable, versionable Markdown summary suitable for:

• human review
• async collaboration
• audits
• GitHub issues / PRs
• IDE panels

JSON remains the source of truth for machines; Markdown becomes the interface for humans.

Definition of Done (DoD)

1. Markdown Is the Default Human Interface

• For every major lifecycle artifact, a corresponding Markdown summary exists
• Users should never need to open raw JSON to understand:
  • what was planned
  • what was executed
  • what changed
  • why something failed or was blocked

2. Required Markdown Artifacts

The following Markdown files are generated automatically:

• plan/plan.md

  • High-level summary
  • Milestones and tasks
  • Task status
  • Constraints and guardrails
  • Planner revisions (if any)

• executions/<task_id>/exec.md

  • Task description
  • Context used
  • Execution result
  • Errors or questions (needs_info)
  • Links to patch and raw artifacts

• executions/<task_id>/patch.md

  • Human-readable diff summary
  • File list
  • High-level explanation of changes
  • Link to patch.diff

3. Markdown Is Generated by Source Code Only

• Markdown files are generated by orchestrator runtime code under src/
• Plans and tasks must never attempt to create Markdown files via patch.diff
• Runtime output is strictly separated from source modifications

4. Deterministic and Idempotent Generation

• Regenerating Markdown for the same JSON input produces identical output
• Re-running a command updates Markdown consistently
• Markdown generation never mutates JSON artifacts

5. Failure-Safe Behavior

• If Markdown generation fails:
  • The main command does not fail
  • A warning is logged to audit.log
  • JSON artifacts remain authoritative
• Markdown generation is additive, not critical-path

6. Clear Linking Between Artifacts

• Markdown files reference related artifacts by path:
  • plan → tasks
  • task → execution → patch
• Navigation between files is obvious without tooling

7. Dogfooding Proof

• Markdown summaries are used during dogfooding of llm-orchestrator itself
• Contributors confirm they can:
  • understand a run without opening JSON
  • review patches using only Markdown + diff

Success Signal

A human can fully understand and review any orchestrator run using only Markdown files, without inspecting raw JSON — making the system approachable, auditable, and collaboration-friendly.