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
+54 -4
View File
@@ -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