Skip to content

v0.8.0: DECISIONS.md projection

Choose a tag to compare

@jarmstrong158 jarmstrong158 released this 03 Jul 10:30

DECISIONS.md projection (opt-in, render-on-write)

Mirror the canonical decisions store into a human-readable DECISIONS.md:

{ "markdown_export": { "enabled": true, "path": "DECISIONS.md" } }
  • Render-on-write. Every decision mutation (record_decision, update_entry, deprecate_entry) regenerates the entire file from decisions.json after the JSON write and before the tool returns -- so a subsequent git commit captures JSON and markdown in the same commit. Deliberately on the write path, not a git/PostToolUse hook: rendering after the commit snapshot is taken would reintroduce drift.
  • JSON stays canonical; markdown is derived and read-only. Regenerated whole every time, never appended to or parsed back. Hand edits are not preserved -- a regenerated projection has no drift surface.
  • New export_markdown tool regenerates on demand (optional custom path), so existing repos can backfill without enabling the flag.
  • Entry layout mirrors the field-tested convention: ### <summary> -- MM-DD (dec-NNN) headings with Why / Tried / Tradeoff / Rejected bullets; pre-v0.4 legacy entries render their freeform rationale as Why.
  • Pure stdlib. Default behavior with the flag off is byte-for-byte unchanged.

131 tests passing (10 new). Smoke-tested against a real 59-decision store.