feat: store discussion prose in Markdown bodies

Add versioned Markdown discussion documents with legacy YAML reading and explicit migration that backs up originals and preserves semantic history.

Render readable discussion and decision prose in Markdown context, document compatibility, and extend native smoke coverage for migration.

Validated with 29 passing tests, macOS ARM64 native smoke, and context-preserving migration of the Zelda pilot Work.
This commit is contained in:
Nilton Constantino
2026-11-11 19:50:36 +00:00
parent e65f216926
commit c84bb8d36f
12 changed files with 353 additions and 18 deletions
@@ -88,14 +88,48 @@ public final class VerificationService {
section(result, "Goal", w.goal()); section(result, "Description", w.description()); section(result, "Motivation", w.motivation());
section(result, "Constraints", items(w.constraints())); section(result, "Acceptance criteria", items(w.acceptanceCriteria()));
section(result, "Repository revisions at Work creation", yaml(w.repositories()));
section(result, "Discussion history and conclusions", yaml(context.discussionHistory()));
section(result, "Decisions (approval status is explicit)", yaml(context.decisions()));
section(result, "Discussion history and conclusions", discussionMarkdown(context.discussionHistory()));
section(result, "Decisions (approval status is explicit)", decisionMarkdown(context.decisions()));
section(result, "Outstanding questions", items(context.outstandingQuestions()));
section(result, "Artifact references (paths relative to Work)", yaml(context.artifacts()));
section(result, "Metadata", "Created: " + w.createdAt() + "\n\nUpdated: " + w.updatedAt() + "\n\nAuthor: " + w.author());
return result.toString();
}
public String discussionMarkdown(List<DiscussionEntry> entries) {
if (entries.isEmpty()) return "None recorded.";
var out = new StringBuilder();
for (var entry : entries) {
if (!out.isEmpty()) out.append('\n');
out.append("### ").append(entry.id()).append(" — ").append(entry.kind()).append("\n\n")
.append("Author: ").append(entry.author()).append("\n\nThread: ").append(entry.discussionId())
.append("\n\nCreated: ").append(entry.createdAt()).append('\n');
if (entry.respondsTo() != null) out.append("\nResponds to: ").append(entry.respondsTo()).append('\n');
out.append('\n').append(entry.text()).append('\n');
}
return out.toString();
}
private static String decisionMarkdown(List<DraftDecision> decisions) {
if (decisions.isEmpty()) return "None recorded.";
var out = new StringBuilder();
for (var decision : decisions) {
if (!out.isEmpty()) out.append('\n');
out.append("### ").append(decision.id()).append(" — ").append(decision.title()).append("\n\n")
.append("Approval: ").append(decision.approvalStatus()).append("\n\nAuthor: ").append(decision.author())
.append("\n\nCreated: ").append(decision.createdAt()).append('\n');
subsection(out, "Context", decision.context()); subsection(out, "Approach", decision.approach());
subsection(out, "Alternatives", items(decision.alternatives())); subsection(out, "Rationale", decision.rationale());
subsection(out, "Risks", items(decision.risks())); subsection(out, "Acceptance criteria", items(decision.acceptanceCriteria()));
subsection(out, "Evidence", items(decision.evidence()));
}
return out.toString();
}
private static void subsection(StringBuilder out, String title, String text) {
out.append("\n#### ").append(title).append("\n\n").append(text.isBlank() ? "None recorded." : text).append('\n');
}
private static String items(List<String> values) { return values.isEmpty() ? "None recorded." : String.join("\n", values.stream().map(v -> "- " + v).toList()); }
private static String yaml(Object value) { return "```yaml\n" + Documents.yaml(value) + "```"; }
private static String yaml(Object value) {
if (value instanceof List<?> list && list.isEmpty()) return "None recorded.";
return "```yaml\n" + Documents.yaml(value) + "```";
}
private static void section(StringBuilder out, String title, String body) { out.append("\n## ").append(title).append("\n\n").append(body.isBlank() ? "None recorded." : body).append('\n'); }
}