deferredwork: dev session writes ledger markdown directly — give it a structured sink the orchestrator renders

[pbean]

Summary

The inner dev session writes deferred-work ledger markdown directly. bmad-dev-auto's
step-04-review.md:69-74 instructs it to append a flat block to {deferred_work_file}:

- source_spec: `{spec_file}`
  summary: <one sentence>
  evidence: <why this is real>

and engine.py:2391-2396 reinforces it in the follow-up-review prompt the orchestrator sends
("append them to the deferred-work ledger as NEW entries only").

This sits awkwardly against deferredwork.py's own module docstring — "The orchestrator never
trusts an LLM to have edited it" — which is true of status flips and decision records, and not true
of entry creation. It is also the reason two recent bugs existed:

• deferredwork: flat appender block after the last canonical DW entry is swallowed — invisible to parse_legacy and never swept #304 / PR fix(deferredwork): keep flat appends visible after canonical entries (#304) #322 — a flat append landing after the last canonical entry was invisible, because
  the boundary between LLM-authored markdown and parsed markdown is guesswork.
• deferredwork: ledger mutators write free text verbatim — a multiline note/detail injects lines (sanitize at chokepoint + validate_triage feedback, not raise) #305 — the writer chokepoint that sanitizes free text sits in front of the smaller producer.
  The dev appender bypasses append_entry entirely, so nothing normalizes what it emits.

Every flat entry also costs a whole extra LLM migration session before it is sweepable
(sweep.py:714-720 — "One LLM session rewrites the legacy items into canonical DW entries").

Design sketch

Give the dev session a structured sink and let orchestrator Python render the ledger.

The channel already exists in two forms — neither needs an upstream fork:

1. Spec frontmatter. devcontract.synthesize_result (devcontract.py:197) already builds the
   dev result dict entirely from spec frontmatter — dev sessions emit no result.json at all
   (devcontract.py:1-10). A deferred: list there is parsed by the existing read_frontmatter.
2. The generic result.json mixin. adapters/generic.py:187-207 is available to any skill that
   writes one; bmad-loop-sweep uses it today. bmad-dev-auto simply doesn't.

Either way the orchestrator calls deferredwork.append_entry per item, so entries arrive canonical
(### DW-<seq>) and pre-sanitized, and has_legacy/migration stops firing for new work.

bmad-dev-auto is upstream and not bundled here (install.py:62-70,
data/skills/README.md:21-23), but the orchestrator already overrides its ledger instructions by
prompt injection at engine.py:2391-2396 — so this is a prompt-contract plus renderer change on the
bmad-loop side, not a fork. An upstream change would be cleaner if Alex is open to it.

What this does NOT replace

A newline inside a JSON or YAML string value is still a real newline once parsed. Structured input
fixes syntax corruption (malformed blocks, broken indentation, boundary ambiguity), not value
content — so deferredwork's _one_line sanitizer from #305 remains load-bearing. What this buys is
making that chokepoint universal instead of partial, and deleting a migration session per flat
defer.

Scope note

Feature-sized: touches the dev contract, the flat-entry parser, migration, and legacy-ledger
handling. Filing for maintainer confirmation before any implementation, per CONTRIBUTING.

Backward compatibility is the main design question — flat appends must keep working for
already-installed bmad-dev-auto versions and for ledgers already containing them, so the renderer
is additive and parse_legacy/migration stay as the fallback path rather than being removed.

[coderabbitai]

🔗 Related PRs

#274 - fix(deferredwork): keep flat appends visible after canonical entries [open]
#277 - feat(adapters,engine,devcontract): deterministic missing-marker catch + repair [merged]
#284 - feat: auto-resolve deferred-work entries a story declares (closes #234) [open]
#300 - feat: story-declared deferred-work closure — the advisory contract (#234) [merged]
#322 - fix(deferredwork): keep flat appends visible after canonical entries (#304) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[pbean]

Upstream ask filed as bmad-code-org/BMAD-METHOD#2636: give defer findings a machine-readable record —
Option A (preferred): spec-frontmatter deferred: list (summary/evidence + optional
location/severity) plus a suppressible ledger projection via a customize.toml
deferred_work_file key (today it is hardcoded in three step frontmatters, no seam);
Option B (offered honestly): enriched, precisely-specified direct append.

Consumption story if A lands: read_frontmatter already parses it (full YAML);
synthesize_result attaches it like followup_review_recommended; engine calls
append_entry per item post-verify — sweep and triage need zero changes (they
only ever see canonical ### DW-n entries), migration stops firing for new work and
stays as the legacy/foreign-producer fallback, and the mid-sweep "legacy-appeared"
abort from a follow-up review's flat append dies with it.

Renderer caveat for this issue's implementation, whichever channel lands:
append_entry's idempotence key is (origin, source_spec) — two deferred items from
the same spec with an identical origin string collide, the second silently dropped as
a replay. Origin must be per-item distinct, or the key widened.

If upstream declines, this issue's prompt-injection + renderer design stands as the
fallback.