Spec markdown export

Here's what I found from reading the repo: **No export mechanism exists today.** None. Zero. There is no markdown renderer, no download button, no "copy as text", no CLI export command, nothing that turns a spec's content into a portable file. **What a spec actually is:** - `specs` row — metadata (title, summary, key, projectId) - `spec_editor_blocks` rows — each block has `type` (goal/constraint/acceptance_criterion/paragraph), `text` (short label like "50-user concurrency cap"), and `attrs` (a JSON Tiptap/ProseMirror rich-text document holding the multi-paragraph body with formatting, links, lists, etc.) - `spec_versions` row — a full content snapshot as JSON **What exists today for getting data OUT:** - `GET /v1/specs/:id/blocks` — JSON of all blocks with their Tiptap-format `attrs` - Share link (`/s/:token`) — a public browser view of the spec, but no file download - Gallery (`apps/web/content/spec-gallery/`) — hand-authored JSON fixtures for the marketing site, not a user-facing export **What exists for getting data IN (the reverse direction):** - `markdownToTiptapDoc` in the agent tools — converts pasted markdown into the editor format. There is no reverse function. --- So: the product has no way to get a spec out as a portable document. You said "people want their specs out" — who specifically? What are they doing today instead that's painful?

Got it. Markdown, human-readable, no backup-format trap. The full-fidelity dump dies here. Let me start the **intent** section with the most scope-defining question. I've set up the opening frame and asked the first question. Here's the spec skeleton so far: **Title:** Spec markdown export **Summary:** Export a finished spec as readable markdown — title, summary, goals, constraints, acceptance criteria, and tasks (TBD which) rendered as structured markdown. **Goals set:** 1. One-click markdown export from the spec editor 2. Human-readable document (no JSON dump, no scores/edges/history) 3. Usable outside Zenorm (GitHub, Notion, Obsidian — standard markdown) **Open question:** What content goes in? My recommendation is option C — core body (title, summary, goals, constraints, acceptance criteria) plus tasks plus key header metadata (linked repo, spec type, date) — enough to stand alone as a document without the Zenorm chrome, but keeping out the raw scores/edges/history that make it a backup dump.

Strong position. Let me capture all of that — the content scope, the trace-relationship requirement, and the critical non-lossiness constraint — then score intent. Let me also check the full set of block types that exist in the codebase so the constraint is calibrated to reality. Good — I can see the block type landscape from the codebase. Among other things, `non_goal` is a real block type (mapped alongside goals in the gallery export). Let me now score intent with the answered content in place. Intent is locked at 0.9. Moving to **constraints**. One big constraint is already captured — the fail-on-unknown-types rule. Now I need to understand the delivery mechanism. Here's where things stand: **Intent** — scored 0.9, locked. - Content in: title, summary, goals, non-goals, constraints, acceptance criteria, tasks, trace relationships (AC↔task as inline human-readable links) - Content out: grilling transcript, section scores, gate history - Non-silent-lossiness: unknown block types cause failure, not silent omission **Constraints so far:** 1. Fail on unknown block types 2. Rich text body (Tiptap JSON attrs → well-formatted markdown, not plain text fallback) **Open question:** Delivery mechanism — button-in-UI, API endpoint, CLI, clipboard, or a mix? My recommendation is both a browser download button **and** an API endpoint (`GET /v1/specs/:id/export?format=md`), so the export is available from the editor *and* scriptable for users who want to commit specs into their repo.

Important discovery: `zenorm pull` already exists and already renders blocks to markdown. But it's optimized for agent consumption (raw block dumps, no trace links, no task rendering, no non-goals, no inline formatting). The human-readable export needs a new or heavily extended render path. Let me capture what I've learned and the decisions made. Constraints at 0.95. Moving to **acceptance**. Most ACs flow directly from the locked goals and constraints. One thing I need a decision on: the trace relationship rendering format you specifically called out as content, not metadata. Let me nail that before writing the rest. Acceptance scored at 0.85 — needs the trace relationship AC locked in to pass 0.9. Here's where we are: **Done this turn:** - Delivery mechanism decided: CLI `zenorm export` + API endpoint. `pull` stays unchanged. - No-import non-goal captured as a product decision. - 6 acceptance criteria inserted covering CLI output, API endpoint, content exclusions, unknown-block-type failure, rich text preservation, and no round-trip. **Still open:** The trace relationship format question from last turn. Your call here determines the last AC — once answered, I'll score acceptance ≥0.9 and generate tasks.

All three sections passed. Let me plan and generate the task. One capability: the renderer, API endpoint, and CLI command are stacked layers of the same user-visible outcome (get a markdown document). One task. Task created. Now the trace graph. Spec is complete. Here's the final state: **Title:** Spec markdown export **Summary:** Export a finished spec as readable markdown — title, summary, goals, non-goals, constraints, acceptance criteria, and tasks rendered as structured markdown a human can paste into Notion, commit alongside code, or share as a file. No full-fidelity JSON dump, no repeatable token-gated view. **4 Goals:** - One-click markdown export (CLI + API) - Human-readable document (full authored content, no scores/transcript/history) - Usable outside Zenorm (standard markdown rendering) - Trace relationships as inline content (ACs quoted under each task) **5 Constraints:** - Fail on unknown block types (never silently skip) - Rich text body converts to markdown formatting - CLI export command + API endpoint - Existing `pull` command unchanged - No markdown import or round-trip (product decision, not just deferred scope) **8 Acceptance Criteria:** 1. `zenorm export <key>` writes or streams markdown 2. API endpoint returns same markdown behind auth 3. No section scores, transcript, or gate history 4. Unknown block type causes hard failure 5. Rich text formatting preserved (bold, italic, code, links, lists) 6. No import or round-trip mechanism 7. Tasks quote the ACs they implement (no bare IDs) 8. Orphan ACs explicitly listed as unimplemented **1 Task:** - `Add zenorm export CLI command for human-readable spec markdown` — owns the server-side renderer (Tiptap JSON → markdown), the `GET /v1/specs/:id/export?format=md` endpoint, and the `zenorm export <ref>` CLI command. Traces to all 8 ACs.