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
+18
View File
@@ -139,6 +139,24 @@ be grouped with `--discussion <name>`. History remains append-only. `work status
WRK-0001 ACTIVE` changes lifecycle status; all initial statuses are reversible.
Every command provides `--help`; inspection commands support `--format json`.
New discussion files keep metadata in YAML front matter (`documentVersion: 2`) and
the complete text in the Markdown body. Headings, lists, tables and code blocks remain
readable directly in an editor. Markdown context/list output also displays prose
directly; JSON continues to expose the same `text` field.
Older discussion files with `text` in YAML are read without being rewritten. To
convert a Work's existing discussions explicitly with the updated CLI:
```sh
ai-engineering discussion migrate WRK-0001
```
Originals are backed up under `.ai-engineering/.local/backups/discussions/`; the
command reports the backup paths. IDs, authors, dates, text, Work metadata and exported
context data are preserved. Running the command again skips converted files. Migration
refuses legacy trailing notes rather than silently dropping them. Use the updated CLI
for files in document version 2; old CLI builds cannot read that new file format.
Exit codes: **0** success, **1** unexpected I/O/runtime failure, **2** invalid input
or unsafe path, **3** missing project/resource, **4** structural validation failure.
Validation commands return 4 with diagnostics even when the underlying issue is a