# Treat this task as a correctness-critical change to the sync layer. The
# importer writes one direction (md → DB); after this task the system MUST
# also write the other direction (DB → md frontmatter) so MCP-driven status
# transitions survive the next importer pass. Be careful with diff noise,
# trailing newlines, and YAML key ordering — the markdown files are
# human-authored.
---
# Task summary
The markdown importer at `packages/database/src/markdown-backlog/sync.ts` is one-way: it reads `plans/**/*.md` and upserts into `markdown_backlog_items`. There is no path back from the DB to the markdown frontmatter. As soon as an agent calls `complete_task` (status → `done`), running the importer would clobber that transition back to whatever the markdown still says.
For now we paper over this by running the importer once at bootstrap and ad-hoc thereafter (`pnpm --filter @tasks/database import:markdown-backlog`). That's tolerable for a single-operator dogfood loop, but it doesn't scale and it's a correctness bug: any change made through the app — status flips, prompt edits, new tasks created in the UI — is at risk of being silently reverted.
This task closes that loop by adding a DB → markdown export.
- Maybe `workspaces.archive` cascade for backlog items (lower priority — archive is a UI-driven verb and the markdown may not need to reflect it).
Out of scope:
- Creating brand-new `.md` files from DB rows (we never UI-create backlog items today; punt to a separate task).
- Two-way conflict resolution. If someone edits both the file and the DB row between importer runs we just take the DB. Document this clearly in `config/CursorSync.md`.
### Implementation notes
- Use a small, well-tested YAML rewriter, not a regex. The `yaml` package (already a dep of `@tasks/database`) supports preserving comments and key order via `Document` parsing. Use `Document.parse(source)`, mutate scalar values in place, and `String(doc)` to serialize.
- File I/O lives in `packages/database/src/markdown-backlog/export.ts`. Keep this module free of tRPC / Next imports so the MCP server can call it directly.
- Status update: `ready` → `done` only mutates `status` and `updated_at`.
- Setting `agent_prompt: null` removes the key (does not write `agent_prompt: null`).
- Block-scalar serialization for multi-line prompts.
- Preserves trailing newline and body separator (`---\n\n` vs `---\n`).
- Behind a workspace-level setting `markdown_export_enabled` (default `true`). Some operators may not want the app rewriting their `plans/` tree; let them opt out.
### Acceptance
1. After calling `complete_task` with `finalStatus: done`, the corresponding `.md` file's frontmatter status reads `done` on disk.
2. Running `pnpm --filter @tasks/database import:markdown-backlog` immediately after produces zero new upserts (the file already matches the DB).
3. Vitest coverage of the export helper.
4.`config/CursorSync.md` is updated to describe the new two-way contract and the conflict policy (DB wins on conflict between importer runs).
5. No diff noise: re-exporting an unchanged row leaves the file byte-identical.
### Risks
- YAML formatting is finicky; agents may produce huge accidental diffs the first time this runs. Mitigate with the round-trip test and an `--dry-run` flag on the export helper for first verification.
- Concurrent writes: an operator editing the `.md` in their editor at the moment of export could lose changes. The atomic write helps but doesn't fully solve it. Document the contract: while agents are running, treat the `.md` files as derived state.
