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
@@ -0,0 +1,90 @@
package net.intrepid.aiengineering;
import net.intrepid.aiengineering.discussion.*;
import net.intrepid.aiengineering.filesystem.*;
import net.intrepid.aiengineering.project.ProjectService;
import net.intrepid.aiengineering.work.WorkService;
import net.intrepid.aiengineering.verification.VerificationService;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.nio.file.*;
import java.util.List;
import static org.assertj.core.api.Assertions.*;
class DiscussionMarkdownTest {
@TempDir Path root;
private final DiscussionService discussions = new DiscussionService();
private final WorkService works = new WorkService();
private void initialize() {
new ProjectService().initialize(root, "Test");
works.create(root, "One", "", "Goal", "", List.of(), List.of(), List.of(), "human");
}
private DiscussionEntry add(String text) {
return discussions.add(root, "WRK-0001", text, DiscussionEntry.Kind.SUGGESTION, "agent", "main", null);
}
private Path path(String id) { return works.folder(root, "WRK-0001").resolve("discussions/" + id + ".md"); }
@Test void newDiscussionPersistsMarkdownProseOutsideFrontMatterAndReloadsExactly() throws Exception {
initialize();
String prose = "\n## Proposta — próxima etapa\n\n- Evidência: árvore\n- 日本語\n\n```yaml\n---\nname: Zelda\n```\n\nÚltima linha sem newline";
var entry = add(prose); String stored = Files.readString(path(entry.id()));
assertThat(stored).contains("documentVersion: 2", "\n---\n\n" + prose).doesNotContain("\ntext:", "\\n");
assertThat(new DiscussionService().list(root, "WRK-0001")).containsExactly(entry);
var context = new VerificationService().context(root, "WRK-0001");
assertThat(new VerificationService().markdown(context)).contains(prose, "### DSC-0001", "SUGGESTION").doesNotContain("text:", "\\n");
assertThat(context.discussionHistory().getFirst().text()).isEqualTo(prose);
}
@Test void legacyYamlRemainsReadableWithoutImplicitWrites() throws Exception {
initialize(); var entry = add("Legacy\n\nLong text.");
String legacy = "---\n" + Documents.yaml(entry).replaceFirst("^---\\n", "") + "---\n";
Files.writeString(path(entry.id()), legacy);
assertThat(new DiscussionService().list(root, "WRK-0001")).containsExactly(entry);
assertThat(Files.readString(path(entry.id()))).isEqualTo(legacy);
}
@Test void explicitMigrationBacksUpOriginalsAndPreservesContextAndWorkMetadata() throws Exception {
initialize(); var one = add("## Long proposal\n\nA → B\n"); var two = add("Second entry");
String oldOne = legacy(one); String oldTwo = legacy(two);
Files.writeString(path(one.id()), oldOne); Files.writeString(path(two.id()), oldTwo);
String contextBefore = Documents.json(new VerificationService().context(root, "WRK-0001"));
String markdownBefore = new VerificationService().markdown(new VerificationService().context(root, "WRK-0001"));
Path work = works.folder(root, "WRK-0001").resolve("work.md"); byte[] before = Files.readAllBytes(work);
var report = discussions.migrate(root, "WRK-0001");
assertThat(report.converted()).isEqualTo(2); assertThat(report.unchanged()).isZero();
assertThat(report.backups()).hasSize(2);
assertThat(Files.readString(root.resolve(report.backups().getFirst()))).isEqualTo(oldOne);
assertThat(Files.readString(root.resolve(report.backups().getLast()))).isEqualTo(oldTwo);
assertThat(Documents.json(new VerificationService().context(root, "WRK-0001"))).isEqualTo(contextBefore);
assertThat(new VerificationService().markdown(new VerificationService().context(root, "WRK-0001"))).isEqualTo(markdownBefore);
assertThat(Files.readAllBytes(work)).isEqualTo(before);
String converted = Files.readString(path(one.id()));
var repeated = discussions.migrate(root, "WRK-0001");
assertThat(repeated.converted()).isZero(); assertThat(repeated.unchanged()).isEqualTo(2); assertThat(repeated.backups()).isEmpty();
assertThat(Files.readString(path(one.id()))).isEqualTo(converted);
}
@Test void migrationRefusesLegacyTrailingNotesBeforeChangingAnyFiles() throws Exception {
initialize(); var one = add("One"); var two = add("Two");
String oldOne = legacy(one); String oldTwo = legacy(two) + "\nUser notes that must not disappear\n";
Files.writeString(path(one.id()), oldOne); Files.writeString(path(two.id()), oldTwo);
assertThatThrownBy(() -> discussions.migrate(root, "WRK-0001")).isInstanceOf(ProtocolException.class).hasMessageContaining("trailing notes");
assertThat(Files.readString(path(one.id()))).isEqualTo(oldOne);
assertThat(Files.readString(path(two.id()))).isEqualTo(oldTwo);
assertThat(Files.exists(root.resolve(".ai-engineering/.local/backups"))).isFalse();
}
@Test void conflictingBodySourcesAndUnknownDocumentVersionsAreRejected() throws Exception {
initialize(); var entry = add("Canonical body"); String valid = Files.readString(path(entry.id()));
for (String invalid : List.of(valid.replace("documentVersion: 2", "documentVersion: 99"),
valid.replace("documentVersion: 2", "documentVersion: \"2\""),
valid.replace("documentVersion: 2", "documentVersion: 2\ntext: ambiguous"),
valid.replace("documentVersion: 2", "documentVersion: 2\nunknownField: true"))) {
Files.writeString(path(entry.id()), invalid);
assertThat(new VerificationService().work(root, "WRK-0001").valid()).isFalse();
}
}
@Test void crlfFrontMatterPreservesBodyBytesIncludingTrailingNewlines() throws Exception {
initialize(); String prose = "## Proposal\r\n\r\nKeep original line endings.\r\n"; var entry = add(prose);
String stored = Files.readString(path(entry.id())); int boundary = stored.indexOf("\n---\n");
String windows = stored.substring(0, boundary + 5).replace("\n", "\r\n") + stored.substring(boundary + 5);
Files.writeString(path(entry.id()), windows);
assertThat(new DiscussionService().list(root, "WRK-0001")).containsExactly(entry);
}
private String legacy(DiscussionEntry entry) { return "---\n" + Documents.yaml(entry).replaceFirst("^---\\n", "") + "---\n"; }
}
@@ -104,7 +104,7 @@ class ProtocolIntegrationTest {
assertThat(ok("--version").out()).isEqualTo("ai-engineering 0.1.0\n");
for (String command : new String[]{"", "init", "project", "project show", "project validate", "repo", "repo add", "repo list",
"work", "work create", "work list", "work show", "work validate", "work context", "discussion", "discussion add",
"decision", "decision draft", "artifact", "artifact add"}) {
"discussion list", "discussion migrate", "decision", "decision draft", "artifact", "artifact add"}) {
var args = new java.util.ArrayList<String>();
if (!command.isEmpty()) args.addAll(java.util.List.of(command.split(" ")));
args.add("--help"); assertThat(ok(args.toArray(String[]::new)).out()).contains("Usage:");