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:
@@ -79,6 +79,13 @@ processor provides command reflection metadata. The Spring AOT tasks are wired b
|
||||
native build plugin. No application arguments are passed through Spring's property
|
||||
parser. The entry point explicitly chooses non-web mode and closes its context.
|
||||
|
||||
Discussion document version 2 separates typed YAML metadata from an opaque Markdown
|
||||
body. The filesystem codec maps that body to the domain record's existing `text`
|
||||
field; it does not infer structure from prose headings. The reader accepts legacy
|
||||
YAML-only text as well. Explicit migration backs up originals, preserves semantic
|
||||
state and skips converted files. Work and draft DEC persistence are unchanged;
|
||||
Markdown context renders discussion/decision prose without YAML escaping.
|
||||
|
||||
## Earlier framework review and migration
|
||||
|
||||
Both implementations were inspected read-only:
|
||||
|
||||
@@ -157,6 +157,36 @@ Native compilation succeeded on macOS ARM64. With `JAVA_HOME` and `GRAALVM_HOME`
|
||||
pointing to nonexistent paths, the expanded smoke passed both the simple-project
|
||||
scenarios (including no Git on PATH) and the multi-repository scenario.
|
||||
|
||||
## H6 — Discussion readability and compatible migration
|
||||
|
||||
The Zelda pilot produced a long suggestion whose YAML string was hard to inspect in
|
||||
an editor. New discussions now store metadata in front matter with `documentVersion: 2`
|
||||
and canonical prose in the Markdown body. Context and discussion-list Markdown output
|
||||
render prose directly. Work/draft DEC storage and JSON record fields are unchanged.
|
||||
|
||||
Six new tests verify exact Unicode/Markdown/whitespace round trips, legacy read-only
|
||||
loading, context-preserving migration and backups, idempotence, refusal of legacy
|
||||
trailing notes, ambiguous/unknown formats, and CRLF front matter. The complete suite
|
||||
passed with **29 tests, 0 failures, 0 errors, 0 skipped**, including Modulith.
|
||||
|
||||
A copy of the actual Zelda Work was staged at
|
||||
`/tmp/aie-zelda-markdown-preview.z3YttK`. Both legacy discussion entries converted
|
||||
successfully, with originals backed up. JSON and Markdown contexts before/after
|
||||
migration compared byte-for-byte equal. The long `DSC-0002` proposal can now be read
|
||||
directly as ordinary paragraphs and lists, without escaped newlines or split words.
|
||||
The source project was not modified during this rehearsal.
|
||||
|
||||
The native smoke additionally constructs a legacy entry, migrates it, verifies the
|
||||
new format, repeats migration to confirm no-op behavior, and compares exported context.
|
||||
The complete native smoke passed on macOS ARM64, including migration without Git
|
||||
on PATH and the existing single-/multi-repository layouts. The converted Zelda copy
|
||||
also validated with the native binary; repeating migration reported zero conversions.
|
||||
|
||||
After the rehearsal, both discussions in the original Zelda Work were explicitly
|
||||
migrated with the native CLI. Original files were retained under the reported `.local`
|
||||
backup directory. JSON context, Markdown context and `work.md` compared byte-for-byte
|
||||
equal before/after conversion; project validation returned `valid: true`, no issues.
|
||||
|
||||
## Limits and next experiment
|
||||
|
||||
CI workflows are provided but have not been executed from this local workspace.
|
||||
|
||||
+54
-4
@@ -77,10 +77,10 @@ processes. The adapter clears inherited `GIT_*` variables and disables optional
|
||||
```
|
||||
|
||||
`work.md`, discussion and decision files contain YAML front matter, delimited by
|
||||
`---`. All semantic content lives in the front matter in this version; trailing
|
||||
Markdown is reserved for noncanonical notes and is not exported. YAML multiline strings
|
||||
remain human-readable. Edit the typed fields to update canonical content. There is no
|
||||
Java object serialization and no dependency on conversation state.
|
||||
`---`. Work and draft DEC files retain their typed fields in front matter; trailing
|
||||
Markdown in those documents remains noncanonical. Discussion files use the Markdown
|
||||
body for prose as described below. There is no Java object serialization and no
|
||||
dependency on conversation state.
|
||||
|
||||
Work fields: `schemaVersion`, `id`, `title`, `description`, `goal`, `motivation`,
|
||||
`constraints[]`, `acceptanceCriteria[]`, `status`, `createdAt`, `updatedAt`, `author`,
|
||||
@@ -108,6 +108,51 @@ coexist. Kinds: NOTE, QUESTION, RESPONSE, SUGGESTION, ASSUMPTION, HYPOTHESIS,
|
||||
INVESTIGATION, ALTERNATIVE, ISSUE, CONCLUSION. Entries are appended, not rewritten.
|
||||
Text is supplied by a human or external agent; the CLI never fabricates conclusions.
|
||||
|
||||
New discussion files have `documentVersion: 2` in front matter and omit the `text`
|
||||
field there. The complete Markdown body supplies `text`, including its original
|
||||
headings, lists, tables, code blocks and whitespace:
|
||||
|
||||
```markdown
|
||||
---
|
||||
schemaVersion: 1
|
||||
id: DSC-0002
|
||||
workId: WRK-0001
|
||||
discussionId: main
|
||||
kind: SUGGESTION
|
||||
author: agent
|
||||
createdAt: '2026-11-11T16:47:32Z'
|
||||
respondsTo: DSC-0001
|
||||
documentVersion: 2
|
||||
---
|
||||
|
||||
## Proposed approach
|
||||
|
||||
Use the next small, testable slice.
|
||||
|
||||
- State the limits.
|
||||
- Identify supporting evidence.
|
||||
```
|
||||
|
||||
One blank line separates the closing delimiter from the body; that formatting line
|
||||
is excluded from `text`. All subsequent whitespace belongs to the prose. LF and CRLF
|
||||
front matter are accepted; the reader does not normalize the body's line endings.
|
||||
`schemaVersion: 1` still describes the protocol record. `documentVersion: 2` describes
|
||||
this file representation, not a change to JSON context fields. Unknown document
|
||||
versions and simultaneous YAML `text` plus a version 2 body fail validation.
|
||||
|
||||
Legacy discussions omit `documentVersion` (or declare 1) and keep canonical `text`
|
||||
in YAML; their trailing body remains noncanonical notes. The new reader accepts both
|
||||
representations without automatic writes. The old CLI cannot read document version 2.
|
||||
|
||||
`discussion migrate <Work>` explicitly converts legacy entries. Every discussion is
|
||||
preflighted before any file is replaced. Nonblank legacy trailing notes cause refusal;
|
||||
incorporate those notes into canonical text first. Original UTF-8 files are backed up
|
||||
under `.local/backups/discussions/<Work>/<operation-id>/` before atomic replacement.
|
||||
Migration preserves all semantic fields, Work timestamps and context JSON/Markdown,
|
||||
and skips already converted entries. It changes formatting, not discussion history.
|
||||
Interrupted migrations can be resumed; completed files are skipped and existing backups
|
||||
are retained. This is per-file publication, not an all-or-nothing multi-file transaction.
|
||||
|
||||
A response must refer to an earlier entry in the same Work. Outstanding questions
|
||||
include QUESTION and ISSUE entries without an explicit RESPONSE or CONCLUSION pointing
|
||||
to them. This mechanical definition does not infer agreement or approval from prose.
|
||||
@@ -148,6 +193,11 @@ files yield byte-identical output across new instances and processes. Export rej
|
||||
broken references or integrity failures. It requires neither a model nor live Git
|
||||
inspection; `project validate` separately verifies live repositories.
|
||||
|
||||
Markdown context renders discussion and decision prose directly, with IDs, authors,
|
||||
timestamps and reply/approval metadata. Empty sections use `None recorded.`. JSON
|
||||
keeps the complete typed records, including discussion `text`, regardless of their
|
||||
on-disk document version. Evidence remains referenced rather than embedded.
|
||||
|
||||
## Write guarantees and recovery
|
||||
|
||||
Protocol mutations hold `.local/write.lock`, an OS lock released automatically at
|
||||
|
||||
Reference in New Issue
Block a user