@drafthq/draft 3.5.3 → 3.7.1

package/skills/init/references/architecture-spec.md

@@ -5,11 +5,13 @@
 Generate `draft/architecture.md` — a graph-primary human-readable engineering reference.
 
 **Output format**:
+
 - Markdown report with Mermaid diagrams, tables, and code blocks
 - **Target length: fidelity-first** — cover all 10 mandatory sections with graph-grounded accuracy and diagram correctness
 - End the document with: `"End of analysis. Queries should reference the .ai-context.md file for token efficiency."`
 
 **CRITICAL — Template Structure Compliance:**
+
 - The output MUST use the EXACT 10-section structure from `core/templates/architecture.md` (§1–§10)
 - Do NOT create freeform/custom section names or resurrect 28-section numbering
 - Do NOT skip mandatory sections — if a section does not apply, include the heading with "N/A — {reason}"
@@ -68,11 +70,13 @@ _(Skip or adapt sections per the Adaptive Sections table above.)_
 ### 1. Executive Summary
 
 Write **one paragraph** that states:
+
 - What the module IS (identity)
 - What it DOES (responsibilities)
 - Its role in the larger system
 
 Follow with a **Key Facts** bullet list:
+
 - Primary language(s) and version
 - Binary / entry-point / package name
 - Architecture style (e.g., distributed master/worker, client-server, daemon, library, microservice, monolith, serverless, CLI tool)
@@ -87,7 +91,7 @@ Follow with a **Key Facts** bullet list:
 
 A compact block optimized for fast AI-agent context loading. Fill in every field that applies; mark others as "N/A":
 
-```
+```text
 **Module**           : {PROJECT_NAME}
 **Root Path**        : ./
 **Language**         : (e.g., C++17, Go 1.21, Python 3.12, TypeScript 5.3, Rust 1.75, Java 21)
@@ -136,11 +140,13 @@ A compact block optimized for fast AI-agent context loading. Fill in every field
 #### 4.1 High-Level Topology
 
 **MANDATORY: Generate a Mermaid `flowchart TD` diagram** showing:
+
 - The main process / service and its internal components (as nested subgraphs)
 - External services and dependencies (as a separate subgraph)
 - Directional arrows showing primary data / control flow
 
 Example structure (adapt to actual codebase):
+
 ```mermaid
 flowchart TD
     subgraph Service["MyService"]
@@ -162,7 +168,8 @@ Write the `GRAPH:module-deps` injection slot into architecture.md:
 If graph build succeeded (Step 1.4.7 completed), write the populated slot content using the diagram from Step 1.4.7. If filtered (>30 modules), include the filter note. Dashed edges indicate circular dependencies.
 
 If graph binary was not found: write the slot with placeholder body so draft:init --graph-only can populate it later:
-```
+
+```text
 <!-- GRAPH:module-deps:START -->
 [Graph data unavailable — run draft:init --graph-only to populate after graph binary is installed]
 <!-- GRAPH:module-deps:END -->
@@ -187,6 +194,7 @@ For CLI tools: parse args → validate → execute → output → exit.
 #### 5.1 Top-Level Orchestrator
 
 For the main controller / manager / app class:
+
 - Describe its role in one sentence.
 - **Owned Components** — table:
 
@@ -198,6 +206,7 @@ For the main controller / manager / app class:
 #### 5.2 Dependency Injection / Wiring Pattern
 
 Describe how components reference each other. Common patterns to look for:
+
 - Constructor injection (Spring, Guice, etc.)
 - Service locator / context struct (C++ pattern)
 - Module system (Python, Node.js imports)
@@ -230,6 +239,7 @@ Use ✓ for direct calls, ✓(RPC) for remote procedure calls, ✓(HTTP) for RES
 **Purpose**: This section captures the **real behavioral architecture** — the primary ways the system moves through time, state, and control flow. It is more valuable for correct code generation and modification than static component descriptions.
 
 The LLM **must** combine:
+
 - The deterministic knowledge graph (modules, edges, entry points, public surfaces, hotspots, call targets)
 - Its full indexed project understanding from the host Cursor / Claude Code / Copilot environment
 - Targeted source reads only for confirmation and detail
@@ -247,6 +257,7 @@ Synthesize the 2–5 most important operational views for the system. Typical ca
 - For plugin / meta-tooling / agent platforms: the core execution or dispatch model (skill/command/agent lifecycle, frontmatter contract enforcement, generation/condensation pipeline, parallel analysis protocol, track/decompose/implement lifecycle, etc.)
 
 Each diagram must be a **stateDiagram-v2**, **sequenceDiagram**, or detailed **flowchart** containing:
+
 - Real actor / state / stage names from the actual codebase
 - Labeled transitions using actual function, message, or event names where possible
 - `alt` / `opt` / `loop` / `critical` where branching, repetition, or error handling exists
@@ -280,7 +291,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
@@ -312,6 +323,7 @@ Synthesize a single, accurate Mermaid diagram (`stateDiagram-v2`, `sequenceDiagr
 #### Sub-Module Guidance (when graph justifies recursion)
 
 When a module has clear internal structure visible in live engine query `get_architecture .packages` (fan-in/out) or live per-package queries:
+
 - Create `##### 7.X.Y {Parent}/{Child}` subsections only for children that have their own meaningful public surface or high internal fan-in.
 - Each sub-module subsection follows the same compact pattern: graph facts + **one mandatory workflow/state diagram** + ≤60 words Design Notes.
 - Do not descend further unless the child itself shows additional clear boundaries in the graph data.
@@ -326,6 +338,7 @@ When a module has clear internal structure visible in live engine query `get_arc
 | (enumerate ALL public methods — at least 5 entries) | | |
 
 **Interaction with Sibling Sub-Modules**:
+
 - Calls `{sibling}/` for {purpose}
 - Called by `{sibling}/` when {trigger}
 - Shares `{base|common}/` types: {list key shared types}
@@ -336,7 +349,8 @@ When a module has clear internal structure visible in live engine query `get_arc
 **Notable Mechanisms**: {caching, retry, batching, scheduling, etc.}
 
 **Error Handling**: How errors propagate within this sub-module and to the parent.
-```
+
+```text
 
 #### Per-Sub-Module Template (Medium — 10–49 files)
 
@@ -357,7 +371,8 @@ When a module has clear internal structure visible in live engine query `get_arc
 ```{language}
 // actual code from the interface header, 10-20 lines
 ```
-```
+
+```text
 
 #### Operation Catalog Template (for ops/handler directories)
 
@@ -379,7 +394,7 @@ Use `"$DRAFT_TOOLS/graph-callers.sh" --symbol <module>` or `"$DRAFT_TOOLS/graph-
 
 For a module like `icebox/` with sub-directories `master/` (200+ files), `slave/` (150+ files), `client/` (20 files), `base/` (40 files):
 
-```
+```text
 #### 7.3 icebox
   [Top-level module deep-dive: role, overall architecture diagram, cross-sub-module interaction]
 
@@ -405,6 +420,7 @@ For a module like `icebox/` with sub-directories `master/` (200+ files), `slave/
 This produces 300–500+ lines for `icebox/` alone, which is proportional to its 917-file complexity.
 
 **MANDATORY for stateful modules and sub-modules**: Include a `stateDiagram-v2` showing state transitions:
+
 ```mermaid
 stateDiagram-v2
     [*] --> Idle
@@ -470,6 +486,7 @@ Table:
 #### 9.2 Registry / Registration Mechanism
 
 Describe how plugins are registered. Common patterns:
+
 - Explicit registry calls in an init file
 - Decorator / annotation-based auto-registration
 - Convention-based discovery (file naming, directory scanning)
@@ -574,6 +591,7 @@ Table:
 #### 12.3 External-Facing API (if distinct from internal)
 
 List endpoints grouped by function. Reference the actual definition files:
+
 - `.proto` files for gRPC / protobuf
 - OpenAPI / Swagger specs for REST
 - GraphQL schema files
@@ -643,6 +661,7 @@ sequenceDiagram
 ```
 
 Each sequence diagram MUST show:
+
 - All participant lifelines (components / services)
 - Request → response arrows with payload descriptions
 - Conditional branches (alt/opt blocks) where logic diverges
@@ -834,13 +853,15 @@ For each significant pattern (typically 4–8), provide a COMPLETE writeup:
 ```
 
 **Anti-Pattern to Avoid**:
+
 ```{language}
 // Show what NOT to do
 // This helps AI agents avoid common mistakes
 ```
 
 **When to Apply**: Guidance on when new code should use this pattern.
-```
+
+```text
 
 **MANDATORY**: Code snippets must be ACTUAL CODE from the codebase, not pseudocode or simplified examples. Include enough context (10-30 lines) to understand the pattern.
 
@@ -1088,7 +1109,8 @@ Write the `GRAPH:proto-map` injection slot into architecture.md.
 If graph build succeeded and proto files exist (Step 1.4.7 completed), write the populated slot content using the diagram from Step 1.4.7.
 
 If graph binary was not found or no proto files exist, write the slot with placeholder:
-```
+
+```text
 <!-- GRAPH:proto-map:START -->
 [Graph data unavailable — run draft:init --graph-only to populate after graph binary is installed]
 <!-- GRAPH:proto-map:END -->
@@ -1130,6 +1152,7 @@ Before finalizing architecture.md, verify your output meets these quality gates.
 **If any depth gate fails: re-read source for the failing sections and expand. Do NOT proceed to .ai-context.md generation until all depth gates pass.**
 
 **Checklist additions:**
+
 - [ ] Graph injection slots populated (GRAPH:module-deps, GRAPH:hotspots, GRAPH:proto-map) if schema.yaml exists
 - [ ] At least 28 + 5 appendices present (including new Appendix E)
 
@@ -1234,6 +1257,7 @@ Fix: Apply the tiered sub-module analysis. For each Large sub-module, create a `
 
 **FAILURE 5 — Missing Operational Diagrams:**
 Detection: Any of these three diagrams is absent from the document:
+
   - §3.3 initialization sequence diagram
   - §7.4 execution topology diagram
   - §16.2 failure decision tree

package/skills/init/references/okf-emitter.md

@@ -38,7 +38,7 @@ and adds `wiki/`. **Every other standard `/draft:init` file is still produced**
 `.ai-profile.md`, `tracks/` + `tracks.md`, `.state/`, `graph/` — exactly as in
 `monolith` mode. Do **not** skip them: emitting only the bundle is a regression.
 
-```
+```text
 draft/
 ├── .ai-context.md         # INDEX ROOT: synopsis (150–250 lines) + Concept Map
 ├── architecture.md        # RENDERED VIEW (generated from bundle; not source of truth)
@@ -130,78 +130,43 @@ Derive concepts from the graph, not by hand:
 
 ## Generation pipeline (M3)
 
-```
+```text
 1. Survey        → existing /draft:init 5-phase + graph snapshot (graph-snapshot.sh)
 2. Plan          → DETERMINISTIC. okf-plan-concepts.sh derives the expected-concept
-                   set from the graph. EVERY package the graph knows about is
-                   required (fan_in ≥ floor → Subsystem; below floor → Module — the
-                   floor only types/orders, it never exempts); entrypoints → required;
-                   only --allow-defer matches are deferred (with a reason). Writes
-                   draft.tmp/.state/concept-plan.json.
+                   set. Discovery order (exclusive of --manifest):
+                     a) Cargo workspace members / npm workspaces / Go modules
+                     b) graph packages (noise-filtered when a language inventory exists)
+                     c) heuristic top-level source dirs
+                   Coarse graph parents (e.g. crates/codegen) become Subsystems;
+                   crate/package names become Modules. Tokenizer noise (str, int, …)
+                   is dropped when unmapped. Writes draft.tmp/.state/concept-plan.json.
                      okf-plan-concepts.sh --repo . [--scope PATH] \
                        [--manifest FILE] [--min-fan-in 2] [--allow-defer GLOB]... \
                        --out draft.tmp/.state/concept-plan.json
-                   This replaces the old in-context concept enumeration — the boundary
-                   of the work is now a tool output, not an LLM judgment, so modules
-                   and sub-modules cannot be silently dropped. (Legacy fan-in
-                   exemption is opt-in via --defer-below-floor.) LOG the counts
-                   (expected/required/deferred) BEFORE writing any page.
-                   `generated_order` is topo-ish (required + high-fan-in first) so
-                   forward cross-links resolve.
-3. Generate      → iterate concept-plan.generated_order; write ONE page per REQUIRED
-                   entry, grounding each from the graph:
-                     x-callers        ← graph-callers.sh --symbol <c>
-                     x-grounded-paths  ← graph-impact.sh  --symbol <c>  (blast radius)
-                     x-hotspot-score   ← hotspot-rank.sh
-                     overview diagrams ← mermaid-from-graph.sh
-                   Record each source path → page in .state/path-to-concept.json.
-                   Loop post-condition: every required concept_id has an output file.
-                   ⚠ Writing pages via shell heredoc without reading x-grounded-paths
-                   sources, or finishing while any required entry is unwritten, is a
-                   completeness failure — not a stylistic one.
-4. Render views  → ai-context.md (synopsis + Concept Map), architecture.md
-                   (concatenated view + coverage banner), wiki/log.md  (see M4).
-5. Validate      → the promotion gate. Run all layers via the orchestrator:
-                     5a. okf-validate-all.sh draft.tmp/wiki \
-                           --repo . \
-                           --plan draft.tmp/.state/concept-plan.json \
-                           --path-index draft.tmp/.state/path-to-concept.json \
-                           --strict --report draft.tmp/.state/validation-report.json
-                   It runs, in order: okf-validate.sh (structure + reverse index +
-                   empty/untyped-page + leftover-template-token + dangling-link checks),
-                   okf-validate-quality.sh (per-type anti-stub / depth / per-section
-                   content / mermaid lint), okf-coverage-check.sh (every required plan
-                   entry → real page).
-                   ANY layer failing ⇒ exit non-zero ⇒ DO NOT atomic-rename.
-                   coverage.md (systems/coverage.md) is regenerated by the coverage
-                   layer; it is tool-owned (marker <!-- okf:coverage-generated -->) —
-                   never hand-author it except deferral reasons in the manifest.
-6. Emit          → mv draft.tmp/ draft/  ONLY IF step 5 exit 0 ; update .state/.
-                   On failure keep draft.tmp/ and surface validation-report.json.
-```
-
-### Validation report schema (`.state/validation-report.json`)
-
-```json
-{ "valid": false, "bundle": "draft.tmp/wiki",
-  "layers": { "structure": "pass", "quality": "pass", "coverage": "fail" } }
+                   LOG counts (expected/required/deferred + discovery[]) BEFORE pages.
+3. Catalog floor → okf-emit-catalog.sh writes a quality-passing MINIMUM page for
+                   every REQUIRED plan entry that is still missing (so XL monorepos
+                   do not depend on the LLM for completeness):
+                     okf-emit-catalog.sh --plan draft.tmp/.state/concept-plan.json \
+                       --bundle draft.tmp/wiki --repo .
+4. Generate/enrich → iterate concept-plan.generated_order; enrich top hotspots
+                   (LLM) beyond the catalog floor. Record path-to-concept.json.
+                   Post-condition: every required concept_id has a non-stub page.
+5. Render views  → okf-render-views.sh (architecture.md + Concept Map + section
+                   indexes). Uses GFM slugs for TOC; rewrites sibling links to
+                   wiki/<section>/…. Then okf-fix-links.sh --draft draft.tmp --fix.
+6. Validate      → promotion gate (order is intentional):
+                     okf-validate-all.sh draft.tmp/wiki \
+                       --plan draft.tmp/.state/concept-plan.json \
+                       --path-index draft.tmp/.state/path-to-concept.json \
+                       --strict --report draft.tmp/.state/validation-report.json
+                   Runs: quality → coverage (rewrites coverage.md) → structure LAST
+                   so coverage relative links are checked. Also run:
+                     okf-fix-links.sh --draft draft.tmp --check
+                   ANY failure ⇒ DO NOT atomic-rename.
+7. Emit          → mv draft.tmp/ draft/  ONLY IF step 6 exit 0 ; update .state/.
 ```
 
-### Component manifest (optional — `--manifest FILE`)
-
-When the graph engine is unavailable (or a repo wants an authoritative list), pass
-a plain-text manifest: one component name per line, `#` comments and blanks ignored.
-Every listed component becomes a REQUIRED concept; `--allow-defer GLOB` still moves
-matches to deferred. Without a manifest the plan comes from the graph, and only if
-both are unavailable does it fall back to a heuristic top-level-dir scan (which it
-marks `degraded: true`).
-
-Page bodies are LLM-narrated for readability **but** the graph-derived
-frontmatter and the `Blast radius`/`Used by` sections are deterministic. To keep
-incremental carry-forward byte-identical (open decision 2), cache the narrated
-prose keyed by the source hash of `x-grounded-paths` — unchanged sources reuse
-the cached narration verbatim.
-
 ## Render views (M4)
 
 Both are produced by the deterministic helper `okf-render-views.sh` (no LLM) —
@@ -254,18 +219,17 @@ section `index.md` tables are the injection slots for the routing tables.
 
 `/draft:init refresh` under `okf` mode:
 
-```
-1. Re-derive the plan: okf-plan-concepts.sh (modules added since last run become
-   REQUIRED — a new package can't slip through a refresh either)
-2. Diff hashes.json vs working tree     → changed source paths
-3. path-to-concept.json                 → affected concept pages
-4. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
-5. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
-6. Re-validate (full gate): okf-validate-all.sh on the bundle with --plan and
-   --path-index. Refresh re-runs structure + quality + coverage — a changed
-   concept must still clear the quality bar, and a newly-required module must
-   still be present.
-7. Append log.md; update hashes.json + path-to-concept.json
+```text
+1. Re-derive the plan: okf-plan-concepts.sh (cargo/npm/go + graph). Modules added
+   since last run become REQUIRED — a new crate cannot slip through a refresh.
+2. Diff plan vs previous concept-plan.json → NEW required concept_ids
+3. Diff hashes.json vs working tree       → changed source paths
+4. path-to-concept.json                   → affected concept pages
+5. okf-emit-catalog.sh for any NEW missing required pages (completeness floor)
+6. Regenerate/enrich changed + new concepts; carry the rest verbatim
+7. Re-render ai-context.md / architecture.md / log.md + okf-fix-links --fix
+8. Re-validate: okf-validate-all + okf-fix-links --check
+9. Append log.md; update hashes.json + path-to-concept.json + concept-plan.json
 ```
 
 A 1-file change regenerates only the concept(s) that file grounds. Unchanged

package/skills/jira/SKILL.md

@@ -7,7 +7,6 @@ description: Unified Jira entry point. Routes to preview (default), create, or r
 
 Single entry point for all Jira workflows: preview Draft tracks as Jira issues, create them via MCP (default = 1 Story per track; --epic = 1 Epic + 1-3 Stories), and review any Jira ticket (epic, story, bug, sub-task) end-to-end.
 
-
 ## Subcommand Routing
 
 Parse `$ARGUMENTS` and dispatch:
@@ -44,6 +43,7 @@ Assignee Display Name: <assignee-name>
 - **Team / Component / Swimlane / Assignee Display Name** — applied as defaults to every issue created by `create`. Empty values are skipped (Jira ignores blank fields).
 
 If a value is missing when needed:
+
 1. Prompt the user for it.
 2. Append to (or create) the `## Jira` section in `draft/workflow.md` so subsequent runs reuse it.
 
@@ -69,7 +69,7 @@ Generate a timestamped `jira-export-<timestamp>.md` (with `jira-export-latest.md
 
 **Flag handling:** Check `$ARGUMENTS` for `--epic` at the very start of this section. If present, set `EPIC_MODE=true` and remove the flag from the working arguments. This flag changes the entire output structure (see Step 2).
 
-## Red Flags — STOP if you're:
+## Red Flags — STOP if you're
 
 - Generating a preview without an approved plan.md
 - Assigning story points inconsistent with task count
@@ -123,7 +123,6 @@ synced_to_commit: "{FULL_SHA}"
 
 ## Mapping Structure
 
-
 ### Default behavior (recommended)
 
 - Every track becomes **exactly 1 Story**.
@@ -137,6 +136,7 @@ This keeps Jira clean and keeps the export focused on root issues by default.
 Use `/draft:jira preview --epic` or `/draft:jira create --epic` when you want an Epic.
 
 **Splitting rule (simple):**
+
 - 5 or fewer phases → **1 Story** under the Epic
 - More than 5 phases → split across **2 or 3 Stories** (maximum)
 
@@ -166,13 +166,16 @@ If no track found: tell the user "No track found. Run `/draft:new-track` to crea
 ## Step 2: Determine Export Mode, Count Phases, and Group Content
 
 ### 2.1 Detect Mode
+
 - If `EPIC_MODE=true` (from `--epic` flag), use Epic + Stories mode.
 - Otherwise, use **default single-Story mode**.
 
 ### 2.2 Count Phases and Decide Story Count (Epic Mode Only)
+
 Count the number of `## Phase` sections in `plan.md`.
 
 **Splitting guideline (when using --epic):**
+
 - Phases ≤ 5  → 1 Story under the Epic
 - Phases 6–12 → 2 Stories under the Epic
 - Phases > 12 → 3 Stories under the Epic (hard cap)
@@ -180,9 +183,11 @@ Count the number of `## Phase` sections in `plan.md`.
 Store the target number of stories: `TARGET_STORIES`.
 
 ### 2.3 Group Phases (for Epic Mode)
+
 Divide the phases as evenly as possible across `TARGET_STORIES`.
 
 Example grouping (store this in memory):
+
 - Story 1 gets phases 1..K
 - Story 2 gets phases K+1..M
 - Story 3 gets remaining phases
@@ -190,13 +195,16 @@ Example grouping (store this in memory):
 In **default mode**, ignore grouping — everything goes under one Story.
 
 ### 2.4 Build Data Structures
+
 For every phase:
+
 - Capture Phase name, Goal, Verification
 - Collect all its tasks (with status)
 
 Calculate total story points using the existing simple table (1-2 tasks = 1pt, 3-4=2pt, 5-6=3pt, 7+=5pt). This total goes on the root issue (or split across stories in epic mode if desired — default is to put total on the first Story).
 
 ### 2.5 Root Issue Data
+
 - Summary = Track title
 - Description base = content from `spec.md` (first 2-3 paragraphs) + later the full structured plan
 - Issue Type = "Story" (default) or "Epic" (--epic)
@@ -230,6 +238,7 @@ SYMLINK="draft/tracks/<track_id>/jira-export-latest.md"
 Create the file and the `latest` symlink.
 
 ### 4.1 Write Frontmatter + Header
+
 Use the standard YAML frontmatter.
 Add a `mode: default` or `mode: epic` field.
 
@@ -266,6 +275,7 @@ Include the Draft signature at the bottom of the description.
 **Jira Content Rule:** Keep every Story description **short and scannable**. Use compact headings and minimal text.
 
 If `mode: epic`:
+
 - Emit 1 to 3 `## Story N: [Short Title]` blocks (using the grouping decided in Step 2).
 - Under each Story, put the phases assigned to it as `### Phase ...` + **compact** task checklists.
 - Each Story gets its share of the total story points (or put the total on the first one — simple is fine).
@@ -276,6 +286,7 @@ Use the existing high-quality bug export format from `bughunt-report-latest.md`.
 These will become real Bug issues linked to the root (Epic or the main Story).
 
 ### 4.5 Final Notes in the Export
+
 Add at the top:
 
 > Default = 1 Story. Use `--epic` for 1 Epic + 1-3 Stories.
@@ -284,7 +295,7 @@ Update the symlink.
 
 ## Step 5: Report
 
-```
+```text
 Jira Preview Generated
 
 Track:   [track_id] - [title]
@@ -317,18 +328,22 @@ Next steps:
 ## Error Handling (preview)
 
 **plan.md has no phases:**
+
 - Tell user: "No phases found in plan.md. Run `/draft:new-track` to generate a proper plan."
 
 **spec.md missing:**
+
 - Use `plan.md` overview for root-issue description.
 - Warn: "spec.md not found, using plan overview for root-issue description."
 
 **jira-export-latest.md already exists:**
+
 - Check if the target file has been manually modified (user-added content not matching generated patterns — edited descriptions, added rows, changed story points from generated values).
 - If modifications detected, prompt: "Existing jira-export appears to have manual edits. Overwrite? [y/N]"
 - If unmodified, proceed with regeneration (new timestamped file + updated symlink).
 
 **Phase has no tasks:**
+
 - Create mid-level issue with 1 story point.
 - Add note: "No leaf issues defined for this phase."
 
@@ -338,7 +353,7 @@ Next steps:
 
 Create Jira issues from `jira-export-latest.md` using MCP-Jira. If no export file exists, auto-generates one first by running the `preview` subcommand.
 
-## Red Flags — STOP if you're:
+## Red Flags — STOP if you're
 
 - Creating Jira issues without reviewing `jira-export-latest.md` first (run `/draft:jira preview`)
 - Proceeding when MCP-Jira is not configured
@@ -372,7 +387,7 @@ Detect MCP-Jira tools. Known tool name variants: `mcp_jira_create_issue`, `jira_
 
 If unavailable:
 
-```
+```text
 MCP-Jira not configured.
 
 To create issues:
@@ -388,14 +403,17 @@ Stop execution.
 ## Step 4: Parse Export File (Export Format)
 
 Read the `mode` field from frontmatter:
+
 - `default` → expect 1 root Story
 - `epic`   → expect 1 Epic + 1–3 Stories
 
 ### Root Issue(s)
+
 - Parse the `## Root Issue` (and any `## Story N:` sections if mode=epic).
 - For each Story section: Summary, Description (which now contains the phases and task checklists), story points if present.
 
 ### Bug Issues
+
 Parse the `## Bug Issues` section completely (same as before). These are always created as separate Bug issues.
 
 **Important:** There are no longer "Mid-Level" or "Leaf Issues" tables that become separate Jira Tasks/Sub-tasks. All work items live inside the Story description(s).
@@ -430,7 +448,7 @@ Assignee Display Name: <assignee-name>
 
 Before creating issues, attempt to fetch project metadata via MCP to verify the project key exists:
 
-```
+```text
 MCP call: get_project (or equivalent)
 - project: [project key]
 ```
@@ -453,7 +471,7 @@ If `Assignee Display Name` is provided, resolve to an account ID via MCP user se
 
 Apply these to every `create_issue` call (omit any that resolved to empty in Step 4b):
 
-```
+```text
 - project: [Project Key]
 - labels: ["draft"]
 - component: [Component if set]
@@ -472,20 +490,21 @@ Apply these to every `create_issue` call (omit any that resolved to empty in Ste
 For each Story/Epic:
 **Jira Content Rule (strict):** The description sent to Jira must be concise. Use short summaries and compact structured sections only. Do not include long reasoning or exhaustive lists.
 
-```
+```text
 MCP call: create_issue
 - issue_type: Story or Epic
 - summary: ...
 - description: [concise content — phases as compact sections, tasks as short checklists]
 + shared field defaults
 ```
+
 Capture the keys.
 
 ### 5b. Create Bug Issues (from Bug Hunt Report)
 
 For every bug parsed in Step 4, create a real **Bug** issue:
 
-```
+```text
 MCP call: create_issue
 - issue_type: Bug
 - summary: ...
@@ -517,7 +536,7 @@ Set export file status to Created (via `jira-export-latest.md`):
 
 ## Step 7: Report (new simplified format)
 
-```
+```text
 Jira Issues Created
 
 Track:   [track_id] - [title]
@@ -543,7 +562,8 @@ Updated:
 ## Error Handling (create)
 
 **MCP call fails:**
-```
+
+```text
 Failed to create [issue type]: [error message]
 
 Partial creation:
@@ -563,7 +583,6 @@ Already-created issues will be detected by keys in jira-export-latest.md.
 
 **plan.md phases don't match export:** warn "Export has N mid-level issues but plan has M phases. Proceeding with export structure." Create based on export.
 
-
 ---
 
 # Subcommand: review
@@ -571,6 +590,7 @@ Already-created issues will be detected by keys in jira-export-latest.md.
 See [review.md](review.md) for the full epic/story/bug/sub-task qualification pipeline. The router delegates to that file when the user invokes `/draft:jira review <JIRA_ID>`.
 
 The review subcommand:
+
 - Accepts any Jira issue ID (epic, story, bug, sub-task) and adapts its depth to the issue type.
 - Runs a 7-phase pipeline: prerequisites → epic/story collection → document/test-plan synthesis → code change collection (Gerrit/GitHub/GitLab) → context synthesis → quality analysis (deep-review + bughunt + coverage) → test gap analysis → report.
 - Produces `draft/jira-review/<JIRA_ID>/qualification-report.md` and (if gaps exist) `remediation-plan.md`.