@drafthq/draft 3.6.0 → 3.7.1

package/scripts/tools/okf-render-views.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # okf-render-views.sh — render the demoted views from an OKF taxonomy bundle.
 #
-# The wiki/ bundle is the source of truth. This produces the two derived,
+# The wiki/ bundle is the source of truth. This produces the derived,
 # human-facing views deterministically (so they never drift from the bundle and
 # carry zero extra maintenance):
 #   1. architecture.md  — a single linear concatenation of every concept page,
@@ -24,6 +24,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=scripts/tools/_lib.sh
 source "$SCRIPT_DIR/_lib.sh"
 
+command -v python3 >/dev/null 2>&1 || {
+    echo "ERROR: python3 is required by ${0##*/} (link rewriting in rendered views)" >&2
+    exit 2
+}
+
 BUNDLE=""
 ARCH_OUT=""
 WEB_OUT=""
@@ -56,7 +61,7 @@ Flags:
                            this tool has no clock dependency).
   --help                   Show this help.
 
-Requires jq (already a Draft prereq) for --web. Exit 0 ok, 1 error, 2 bundle not found.
+Requires jq (for --web) and python3 (link rewriting). Exit 0 ok, 1 error, 2 bundle not found.
 EOF
 }
 
@@ -100,8 +105,6 @@ ordered_pages() {
     done
 }
 
-# Strip YAML frontmatter from a page (leading --- ... --- block on line 1).
-
 # Rewrite markdown links so concatenated architecture.md (at draft/) resolves them.
 # stdin body; $1 = bundle-relative path e.g. systems/foo.md
 rewrite_body_links() {
@@ -133,6 +136,7 @@ sys.stdout.write(re.sub(r"\[([^\]]*)\]\(([^)]+)\)", repl, text))
 ' "$sec"
 }
 
+# Strip YAML frontmatter from a page (leading --- ... --- block on line 1).
 strip_frontmatter() {
     awk '
         NR==1 && /^---$/ { fm=1; next }
@@ -217,6 +221,7 @@ render_architecture() {
             strip_frontmatter "$BUNDLE/$rel" | rewrite_body_links "$rel"
         done < <(ordered_pages)
     } >"$tmp"
+    apply_dest_mode "$tmp" "$out"   # mktemp is 0600; mv would strip the dest's mode
     mv "$tmp" "$out"
     if [[ -x "$SCRIPT_DIR/okf-fix-links.sh" ]]; then
         draft_dir="$(cd "$(dirname "$out")" && pwd)"
@@ -243,12 +248,7 @@ build_concept_map() {
         [[ -n "$type" ]] || continue
         title="$(get_yaml_field "$page" title)"
         [[ -n "$title" ]] || title="$rel"
-        # description may be a folded (>) block — take the first non-empty body line.
-        desc="$(awk '
-            NR==1&&/^---$/{fm=1;next} fm&&/^---$/{exit}
-            fm && /^description:/ { collect=1; sub(/^description:[[:space:]]*>?[[:space:]]*/,""); if($0!=""){print; exit} next }
-            fm && collect { sub(/^[[:space:]]+/,""); if($0!=""){print; exit} }
-        ' "$page")"
+        desc="$(page_desc "$page")"
         echo "| [${title}](${rel}) | ${type} | ${desc} |"
     done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
 }
@@ -313,14 +313,18 @@ inject_concept_map() {
         /<!-- CONCEPT-MAP:END -->/ { skip=0 }
         !skip { print }
     ' "$target" >"$tmp"
+    apply_dest_mode "$tmp" "$target"   # mktemp is 0600; mv would strip the dest's mode
     mv "$tmp" "$target"
     echo "injected Concept Map → $target"
 }
 
 # --- 3. Render a self-contained offline HTML viewer (single file) ---
 # All pages are inlined as JSON; a small built-in markdown renderer draws them in
-# the browser. No server, no internet, no CDN. jq encodes page content safely
-# (and we neutralize any literal </ so embedded "</script>" can't break parsing).
+# the browser. No server, no internet, no CDN. jq encodes page content safely,
+# and the whole emitted data block is passed through a `</` → `<\/` filter: JSON
+# escaping does NOT stop a literal "</script>" from closing the <script> element,
+# and page titles/types/paths come from repo-derived frontmatter, so every field
+# has to be neutralized, not just the markdown body.
 render_web() {
     local out="$1"
     command -v jq >/dev/null 2>&1 || { echo "ERROR: --web requires jq" >&2; return 1; }
@@ -388,14 +392,14 @@ HTML_HEAD
                 "$(jq -Rn --arg v "$rel" '$v')" \
                 "$(jq -Rn --arg v "$title" '$v')" \
                 "$(jq -Rn --arg v "$type" '$v')" \
-                "$(strip_frontmatter "$page" | jq -Rs . | sed 's#</#<\\/#g')"
+                "$(strip_frontmatter "$page" | jq -Rs .)"
         done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
         echo "};"
         # ORDER: bundle root index.md first, then everything else sorted.
         echo "const ORDER = Object.keys(PAGES).sort(function(a,b){"
         echo "  if(a==='index.md') return -1; if(b==='index.md') return 1;"
         echo "  return a<b?-1:a>b?1:0; });"
-    } >>"$tmp"
+    } | sed 's#</#<\\/#g' >>"$tmp"
 
     cat >>"$tmp" <<'HTML_TAIL'
 function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');}
@@ -487,6 +491,7 @@ show(decodeURIComponent(location.hash.slice(1)) || ORDER[0]);
 HTML_TAIL
 
     mkdir -p "$(dirname "$out")"
+    apply_dest_mode "$tmp" "$out"   # mktemp is 0600; mv would strip the dest's mode
     mv "$tmp" "$out"
     echo "rendered offline HTML viewer → $out ($(find "$BUNDLE" -type f -name '*.md' | grep -c .) pages)"
 }

package/scripts/tools/okf-validate-quality.sh

@@ -73,6 +73,17 @@ body_of() {
     awk 'NR==1&&/^---$/{fm=1;next} fm&&/^---$/{fm=0;next} !fm{print}' "$1"
 }
 
+# Body text the Q-TEMPLATE scan is allowed to see: fenced code blocks and
+# shell-style ${VAR} expansions removed. Both legitimately carry {ALL_CAPS}
+# spans that are not unreplaced placeholders (a page quoting `${HOME}` or a CI
+# snippet would otherwise fail).
+template_scan_body() {
+    body_of "$1" | awk '
+        /^[[:space:]]*```/ { fence = !fence; next }
+        !fence { gsub(/\$\{[A-Za-z_][A-Za-z0-9_]*\}/, ""); print }
+    '
+}
+
 # Count body lines after the frontmatter close (Q-LEN = "lines after frontmatter").
 body_lines() { body_of "$1" | wc -l | tr -d ' '; }
 
@@ -114,7 +125,7 @@ mermaid_lint() {
         echo "unicode arrow in mermaid (use --> not →)"; return 1
     fi
     # '&' node chaining (common breaker).
-    if printf '%s' "$blocks" | grep -qE '[A-Za-z0-9_]\s*&\s*[A-Za-z0-9_]'; then
+    if printf '%s' "$blocks" | grep -qE '[A-Za-z0-9_][[:space:]]*&[[:space:]]*[A-Za-z0-9_]'; then
         echo "'&' node chaining in mermaid"; return 1
     fi
     # Reserved bareword node ids.
@@ -235,7 +246,7 @@ while IFS= read -r -d '' page; do
     fi
 
     # Q-TEMPLATE: unreplaced {TOKEN} placeholders.
-    if body_of "$page" | grep -qE "$TOKEN_RE"; then
+    if template_scan_body "$page" | grep -qE "$TOKEN_RE"; then
         fail "$rel" "Q-TEMPLATE" "unreplaced template token {PLACEHOLDER}"
     fi
 

package/scripts/tools/okf-validate.sh

@@ -176,14 +176,25 @@ while IFS= read -r -d '' page; do
     fi
 done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
 
+# Page text the {ALL_CAPS} template-token scan is allowed to see. Fenced code
+# blocks and shell-style ${VAR} expansions are removed first: both legitimately
+# contain {ALL_CAPS} spans that are NOT unreplaced placeholders, and a wiki page
+# quoting `${HOME}` or a CI snippet would otherwise fail the whole bundle.
+template_scan_text() {
+    awk '
+        /^[[:space:]]*```/ { fence = !fence; next }
+        !fence { gsub(/\$\{[A-Za-z_][A-Za-z0-9_]*\}/, ""); print }
+    ' "$1"
+}
+
 # --- 3b. Unreplaced template tokens (any page, including index pages) ---
 # Quality checks skip index.md pages, so a leftover {SECTION_TITLE}/{PROJECT_NAME}
 # placeholder in a hand-seeded index would otherwise survive. Match {ALL_CAPS}
 # tokens (safe: real prose almost never contains them).
 while IFS= read -r -d '' page; do
     prel="${page#"$BUNDLE/"}"
-    if grep -qE '\{[A-Z][A-Z0-9_]+\}' "$page" 2>/dev/null; then
-        tok="$(grep -oE '\{[A-Z][A-Z0-9_]+\}' "$page" | head -1)"
+    tok="$(template_scan_text "$page" 2>/dev/null | grep -oE '\{[A-Z][A-Z0-9_]+\}' | head -1 || true)"
+    if [[ -n "$tok" ]]; then
         add_error "$prel: unreplaced template token '$tok'"
     fi
 done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)

package/scripts/tools/parse-git-log.sh

@@ -63,6 +63,13 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
     exit 1
 fi
 
+# `git log -n <non-numeric>` parses the count as 0 and exits 0, so a typo'd
+# --limit silently yields an empty stream. Reject it here instead.
+if [[ -n "$LIMIT" && ! "$LIMIT" =~ ^[0-9]+$ ]]; then
+    echo "ERROR: --limit must be a non-negative integer (got '$LIMIT')" >&2
+    exit 1
+fi
+
 # Format: delimiter-separated metadata line, then --name-only file list, blank line separator.
 GIT_ARGS=(log --pretty=tformat:'COMMIT%x1f%H%x1f%an%x1f%aI%x1f%s' --name-only --no-merges)
 [[ -n "$SINCE" ]] && GIT_ARGS+=(--since="$SINCE")
@@ -118,6 +125,17 @@ process_commit() {
 
 # Single git log stream: each commit is `COMMIT<US>sha<US>author<US>ts<US>subject`
 # followed by its file paths (one per line) and a blank separator.
+#
+# Staged through a temp file rather than `< <(git ...)`: a process substitution
+# swallows git's exit status, so a bad --branch/--since/--limit produced an empty
+# JSONL stream and exit 0 — indistinguishable from "this range has no commits".
+GIT_OUT="$(mktemp)"
+trap 'rm -f "$GIT_OUT"' EXIT
+if ! git "${GIT_ARGS[@]}" >"$GIT_OUT"; then
+    echo "ERROR: git log failed (check --branch / --since / --limit)" >&2
+    exit 1
+fi
+
 cur_sha=""; cur_author=""; cur_ts=""; cur_subject=""; cur_files=0
 while IFS= read -r line; do
     if [[ "$line" == COMMIT$'\x1f'* ]]; then
@@ -129,7 +147,7 @@ while IFS= read -r line; do
     elif [[ -n "$line" ]]; then
         cur_files=$((cur_files + 1))
     fi
-done < <(git "${GIT_ARGS[@]}")
+done < "$GIT_OUT"
 if [[ -n "$cur_sha" ]]; then
     process_commit "$cur_sha" "$cur_author" "$cur_ts" "$cur_subject" "$cur_files"
 fi

package/scripts/tools/resolve-tools.sh

@@ -7,6 +7,14 @@
 # See core/shared/tool-resolver.md for the canonical procedure and the inline preamble
 # skills embed (this script is the single source of truth for the resolution order).
 #
+# Resolution order is deliberately "authoritative install first, cwd last":
+# skills execute whatever this prints, and the cwd is the repository under review,
+# which Draft routinely runs against untrusted code. A project that ships its own
+# scripts/tools/ must never shadow the installed plugin.
+#
+# Working on Draft itself? Export DRAFT_PLUGIN_ROOT="$PWD" — the explicit override
+# is step 1 and always wins.
+#
 # Usage:
 #   DRAFT_TOOLS="$(scripts/tools/resolve-tools.sh)"   # prints the dir, exit 0 if found
 #   scripts/tools/resolve-tools.sh || echo "tools not found"   # exit 1 if none exist
@@ -21,8 +29,18 @@ esac
 
 newest() {
   # Echo the lexically-newest existing match of a glob (by version sort), or nothing.
+  # `|| true` is load-bearing: on a glob miss `ls` exits non-zero, pipefail
+  # propagates it, and errexit would abort the whole resolver instead of letting
+  # the remaining fallbacks run.
   # shellcheck disable=SC2086
-  ls -d $1 2>/dev/null | sort -V | tail -1
+  ls -d $1 2>/dev/null | sort -V | tail -1 || true
+}
+
+# Is DIR Draft's own source checkout? Checked before trusting the cwd at all.
+is_draft_checkout() {
+  [ -f "$1/scripts/tools/resolve-tools.sh" ] || return 1
+  [ -f "$1/.claude-plugin/plugin.json" ] || return 1
+  grep -q '"name"[[:space:]]*:[[:space:]]*"draft"' "$1/.claude-plugin/plugin.json" 2>/dev/null
 }
 
 resolve() {
@@ -32,10 +50,6 @@ resolve() {
   d="${DRAFT_PLUGIN_ROOT:-}/scripts/tools"
   [ -n "${DRAFT_PLUGIN_ROOT:-}" ] && [ -d "$d" ] && { printf '%s' "$d"; return 0; }
 
-  # 1b. Dev / dogfooding: cwd IS the draft repo. Guarded by this script's own
-  # presence so it can never misfire in a user project (which has no resolve-tools.sh).
-  [ -f "$PWD/scripts/tools/resolve-tools.sh" ] && { printf '%s' "$PWD/scripts/tools"; return 0; }
-
   # 2. Install marker written by `draft install` (authoritative).
   local marker="$HOME/.cache/draft/plugin-root"
   if [ -f "$marker" ]; then
@@ -68,9 +82,11 @@ resolve() {
   d="$HOME/.cursor/plugins/local/draft/scripts/tools"
   [ -d "$d" ] && { printf '%s' "$d"; return 0; }
 
-  # 8. Dev / dogfooding (running inside the draft repo itself).
-  d="$PWD/scripts/tools"
-  [ -d "$d" ] && { printf '%s' "$d"; return 0; }
+  # 8. Last resort — dev / dogfooding inside Draft's own checkout. Deliberately
+  # after every install location, and gated on the plugin manifest rather than on
+  # a same-named file: a bare `$PWD/scripts/tools` test matched any project using
+  # that very common layout and handed it script execution.
+  is_draft_checkout "$PWD" && { printf '%s' "$PWD/scripts/tools"; return 0; }
 
   return 1
 }

package/scripts/tools/verify-citations.sh

@@ -189,8 +189,7 @@ scan_one_track() {
 
     while IFS= read -r f; do
         local rel_md="${f#"$track_dir/"}"
-        while IFS=$'\t' read -r md_file lineno cite; do
-            local md_line="$md_file"
+        while IFS=$'\t' read -r _md_file lineno cite; do
             local result rc=0
             # set +e to capture rc; set -e would exit on a non-zero return.
             set +e

package/scripts/tools/verify-doc-anchors.sh

@@ -3,12 +3,16 @@
 
 #
 # Verify cross-document references in a track:
-# - §X.Y or §X numbered-section references → target document must contain
-# a heading whose text starts with that number.
 # - <doc>.md#<anchor> markdown anchors → resolve <anchor> against the
 # target file's header slugs.
 # - (planned) / [New file ...] annotations → file MUST NOT exist locally.
 #
+# Plain-prose `§X.Y` references are deliberately NOT validated: authors use them
+# as shorthand for an external doc (`architecture.md §20.2`) without naming the
+# file on the same line, so attribution is guesswork. A track that wants a
+# machine-checkable §-reference writes it as a markdown link to the heading,
+# which the anchor check above already covers.
+#
 # Skips content inside <!-- VERIFIER:IGNORE START --> ... END --> blocks.
 #
 # Usage:
@@ -35,7 +39,7 @@ TRACK_PATHS=()
 usage() {
     local stream=2 code=2
     if [[ "${USAGE_HELP_MODE:-0}" == 1 ]]; then stream=1; code=0; fi
-    sed -n '2,20p' "$0" >&$stream
+    sed -n '2,26p' "$0" >&$stream
     exit "$code"
 }
 
@@ -72,24 +76,15 @@ md_slugs() {
             s = tolower(s)
             # Replace spaces with dashes
             gsub(/ +/, "-", s)
-            # Strip punctuation except dashes
-            gsub(/[^a-z0-9-]/, "", s)
+            # Strip punctuation except dashes and underscores. GitHub keeps `_`
+            # in a heading slug (and so does _lib.sh:gfm_slug) — stripping it
+            # here reported every valid #foo_bar-style anchor as missing.
+            gsub(/[^a-z0-9_-]/, "", s)
             print s
         }
     ' "$1" | sort -u
 }
 
-# Extract numbered headers (e.g. "## 7 Parallel SST transfer" or "## 20.2 ...").
-md_numbered_headers() {
-    awk '
-        /^#{1,6} +[0-9]+(\.[0-9]+)*[ .]/ {
-            s = $0
-            sub(/^#+ +/, "", s)
-            print s
-        }
-    ' "$1"
-}
-
 scan_md() {
     local track_dir="$1" md="$2"
     local rel_track="${track_dir#"$REPO_ROOT/"}"
@@ -101,22 +96,7 @@ scan_md() {
         if [[ "$line" == *"<!-- VERIFIER:IGNORE END -->"* ]]; then ignore=0; continue; fi
         (( ignore )) && continue
 
-        # 1. §-references inside a markdown link.
-        # Plain-prose `§X.Y` is too ambiguous in practice — authors commonly
-        # use it as shorthand for an external doc (e.g. `architecture.md §20.2`)
-        # without naming the file on the same line. To keep this validator
-        # focused on machine-verifiable cross-references, we only check
-        # §X.Y when it appears INSIDE a markdown link target — i.e. the
-        # author has structurally committed to an in-track reference.
-        # Example that IS validated:
-        # [see §3.1](./hld.md#detailed-design) ← anchor check below
-        # Example that is NOT validated (prose only):
-        # The §20.2 layout matches architecture.md.
-        # If a track wants stricter intra-track §-checks, it can use
-        # markdown links pointing to numbered headers explicitly.
-        : # §-ref prose validation disabled — see comment above.
-
-        # 2. Markdown anchor references like ./hld.md#section-name
+        # 1. Markdown anchor references like ./hld.md#section-name
         if echo "$line" | grep -qE '\([^)]*\.md#[A-Za-z0-9_-]+\)'; then
             local m
             while IFS= read -r m; do
@@ -141,7 +121,7 @@ scan_md() {
             done < <(echo "$line" | grep -oE '\([^)]*\.md#[A-Za-z0-9_-]+\)')
         fi
 
-        # 3. (planned) / [New file ...] annotations: the path mentioned on the
+        # 2. (planned) / [New file ...] annotations: the path mentioned on the
         # same line must NOT yet exist relative to the track.
         #
         # Only fire when the line has EXACTLY one path-looking token. Lines

package/scripts/tools/verify-graph-binary.sh

@@ -2,6 +2,7 @@
 # verify-graph-binary.sh — validate and select the Draft knowledge-graph engine.
 #
 # The engine is the codebase-memory-mcp binary. Resolution order (see _lib.sh:find_memory_bin):
+#   0. DRAFT_MEMORY_DISABLE — hard off; resolution stops here and reports "none"
 #   1. DRAFT_MEMORY_BIN override
 #   2. codebase-memory-mcp on $PATH
 #   3. Draft-managed install (~/.cache/draft/bin/)
@@ -32,7 +33,8 @@ usage() {
 verify-graph-binary.sh — Draft knowledge-graph engine resolver + verifier
 
 Engine: codebase-memory-mcp
-Resolution: DRAFT_MEMORY_BIN > PATH > ~/.cache/draft/bin > bin/<arch>/
+Resolution: DRAFT_MEMORY_DISABLE (hard off) > DRAFT_MEMORY_BIN > PATH
+            > ~/.cache/draft/bin > bin/<arch>/
 
 Options:
   --repo DIR         Repo root for context (default .)
@@ -95,15 +97,23 @@ classify_source() {
 
 MEMORY_BIN=""
 if ! find_memory_bin "$REPO_ABS" "$SELF_REPO"; then
-  if [[ $EMIT_JSON -eq 1 ]]; then
+  # DRAFT_MEMORY_DISABLE short-circuits resolution, so say so — "install it or
+  # put it on PATH" is the wrong remedy when an env var turned the engine off.
+  if [[ -n "${DRAFT_MEMORY_DISABLE:-}" ]]; then
+    local_msg="Graph engine disabled by DRAFT_MEMORY_DISABLE (unset it to re-enable resolution)"
+  else
     local_msg="No codebase-memory-mcp engine found in DRAFT_MEMORY_BIN, PATH, ~/.cache/draft/bin, or bin/<arch>/"
+  fi
+  if [[ $EMIT_JSON -eq 1 ]]; then
     if [[ $STRICT -eq 1 ]]; then
       printf '{"status":"none","engine_bin":null,"source":null,"arch":"%s","message":"strict mode: %s"}\n' "$ARCH" "$local_msg"
     else
       printf '{"status":"unavailable","engine_bin":null,"source":null,"arch":"%s","message":"%s"}\n' "$ARCH" "$local_msg"
     fi
   elif [[ $STRICT -eq 1 ]]; then
-    echo "STRICT: No codebase-memory-mcp engine found." >&2
+    echo "STRICT: $local_msg" >&2
+  elif [[ -n "${DRAFT_MEMORY_DISABLE:-}" ]]; then
+    echo "ERROR: $local_msg" >&2
   else
     echo "ERROR: No Draft graph engine located (codebase-memory-mcp)." >&2
     echo "        Install it (scripts/fetch-memory-engine.sh) or put it on PATH." >&2

package/skills/GRAPH.md

@@ -8,16 +8,19 @@
 ## Two-Tier Architecture
 
 ### Primary Workflow (4 commands)
-```
+
+```text
 init → new-track → implement → review
                        ↑           |
                        └───────────┘  (auto-invoked at phase boundaries)
 ```
 
 ### Routed Core Workflows (5 routers)
+
 The 5 routers (`/draft:plan`, `/draft:ops`, `/draft:docs`, `/draft:discover`, `/draft:jira`) provide intent analysis and dispatch to the leaf specialist skills. Primary commands and routers are the public surface; leaves remain for compatibility and direct scripting.
 
 ### Specialist Leaf Commands
+
 Grouped into subsystems dispatched by the routers (or primary commands).
 
 ---
@@ -215,7 +218,8 @@ graph TD
 ## Execution Chains
 
 ### Standard Development Flow
-```
+
+```text
 init → new-track → implement → review → (git push + PR)
                        ↑           |
                        └───────────┘
@@ -223,33 +227,38 @@ init → new-track → implement → review → (git push + PR)
 ```
 
 ### Bug Fix Flow
-```
+
+```text
 new-track (bug) → debug → implement → review
                     ↑                      |
                     └──────────────────────┘ (iterate if fix incomplete)
 ```
 
 ### Incident Response Flow
-```
+
+```text
 incident-response → debug → implement → review
         |
         └→ documentation (post-incident report)
 ```
 
 ### Operations Flow
-```
+
+```text
 standup ←── status (reads tracks + git log)
 deep-review ──→ tech-debt ──→ new-track (prioritized items)
 ```
 
 ### Monorepo Flow
-```
+
+```text
 init (root)       → whole-repo code-graph spine + sparse root map
 init (sub-module) → module snapshot + root-link.json → cross-module context via the root spine
 ```
 
 ### Quality Audit Flow
-```
+
+```text
 init → quick-review (fast sanity check)
 init → review (full three-stage)
 init → bughunt (14-dimension sweep)
@@ -259,14 +268,16 @@ init → decompose (optional pre-step for large modules)
 ```
 
 ### Jira Integration Flow
-```
+
+```text
 new-track → jira (preview / create / review subcommands)
                 ↑
          bughunt + review reports (optional enrichment)
 ```
 
 ### Learning Flow
-```
+
+```text
 init → learn → (updates guardrails.md)
                     ↓
          All quality skills read guardrails.md
@@ -290,7 +301,7 @@ init → learn → (updates guardrails.md)
 
 ## Artifact Flow
 
-```
+```text
                     ┌─────────────────────────────────────────────┐
                     │              draft/.state/                   │
                     │  freshness.json  signals.json  run-memory   │