@drafthq/draft 3.5.3 → 3.7.1

package/scripts/tools/okf-validate.sh

@@ -66,7 +66,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --path-index) PATH_INDEX="$2"; shift 2;;
+        --path-index) PATH_INDEX="${2:?--path-index requires a value}"; shift 2;;
         --reverse) REVERSE=1; shift;;
         --structure-only) STRUCTURE_ONLY=1; shift;;
         --json) JSON=1; shift;;
@@ -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)
@@ -237,12 +248,14 @@ if [[ -n "$PATH_INDEX" ]]; then
         # themselves end in .md (e.g. grounding to docs/INVARIANTS.md) — those are
         # not bundle pages, so we extract strings *inside* the [ ... ] value arrays
         # and ignore keys entirely. Each page must exist in the bundle.
+        # Flatten first: the index may be pretty-printed, so value arrays can
+        # span lines and a line-oriented match would silently skip them.
         while IFS= read -r ref; do
             [[ -z "$ref" ]] && continue
             if [[ ! -f "$BUNDLE/$ref" ]]; then
                 add_error "path-index references missing concept page: $ref"
             fi
-        done < <(grep -oE '\[[^]]*\]' "$PATH_INDEX" 2>/dev/null \
+        done < <(tr '\n' ' ' < "$PATH_INDEX" 2>/dev/null | grep -oE '\[[^]]*\]' \
                    | grep -oE '"[^"]+\.md"' | tr -d '"' | sort -u)
     fi
 fi
@@ -251,9 +264,10 @@ fi
 # Forward proves the index doesn't name ghosts; reverse proves no page is an
 # orphan with no source mapping (a symptom of hand-written / off-plan pages).
 if [[ $REVERSE -eq 1 && $STRUCTURE_ONLY -eq 0 && -n "$PATH_INDEX" && -f "$PATH_INDEX" ]]; then
-    # All pages the index maps to (its array values).
+    # All pages the index maps to (its array values). Flattened for the same
+    # pretty-printed-array reason as the forward check above.
     INDEXED_FILE="$(mktemp)"
-    grep -oE '\[[^]]*\]' "$PATH_INDEX" 2>/dev/null \
+    tr '\n' ' ' < "$PATH_INDEX" 2>/dev/null | grep -oE '\[[^]]*\]' \
         | grep -oE '"[^"]+\.md"' | tr -d '"' | sort -u > "$INDEXED_FILE" || true
     while IFS= read -r -d '' page; do
         rel="${page#"$BUNDLE/"}"

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

@@ -49,10 +49,10 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --since) SINCE="$2"; shift 2;;
-        --limit) LIMIT="$2"; shift 2;;
-        --scope-pattern) SCOPE_PATTERN="$2"; shift 2;;
-        --branch) BRANCH="$2"; shift 2;;
+        --since) SINCE="${2:?--since requires a value}"; shift 2;;
+        --limit) LIMIT="${2:?--limit requires a value}"; shift 2;;
+        --scope-pattern) SCOPE_PATTERN="${2:?--scope-pattern requires a value}"; shift 2;;
+        --branch) BRANCH="${2:?--branch requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -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/parse-reports.sh

@@ -35,7 +35,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --root) ROOT="$2"; shift 2;;
+        --root) ROOT="${2:?--root requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac

package/scripts/tools/render-track.sh

@@ -48,7 +48,7 @@ TO_STDOUT=0
 while (($#)); do
     case "$1" in
         -h|--help) USAGE_HELP_MODE=1 usage ;;
-        --out) OUT_PATH="$2"; shift 2 ;;
+        --out) OUT_PATH="${2:?--out requires a value}"; shift 2 ;;
         --stdout) TO_STDOUT=1; shift ;;
         -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
         *) TRACK_DIR="$1"; shift ;;

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/run-coverage.sh

@@ -51,7 +51,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --path) COVERAGE_PATH="$2"; shift 2;;
+        --path) COVERAGE_PATH="${2:?--path requires a value}"; shift 2;;
         --schema-check) SCHEMA_CHECK="true"; shift;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;

package/scripts/tools/scan-markers.sh

@@ -6,7 +6,7 @@
 #
 # Usage:
 # scripts/tools/scan-markers.sh [--root DIR] [--markers LIST]
-# [--min-age-days N] [--include-untracked]
+# [--min-age-days N]
 #
 # Exit codes: 0 OK (even with zero hits), 1 invocation error, 2 not a git repo
 # (emits [] on stdout so consumers can still parse).
@@ -38,9 +38,9 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --root) ROOT="$2"; shift 2;;
-        --markers) MARKERS="$2"; shift 2;;
-        --min-age-days) MIN_AGE="$2"; shift 2;;
+        --root) ROOT="${2:?--root requires a value}"; shift 2;;
+        --markers) MARKERS="${2:?--markers requires a value}"; shift 2;;
+        --min-age-days) MIN_AGE="${2:?--min-age-days requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac

package/scripts/tools/validate-frontmatter.sh

@@ -43,8 +43,8 @@ REQUIRED="name,description"
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --require) REQUIRED="$2"; shift 2;;
-        --mode) MODE="$2"; shift 2;;
+        --require) REQUIRED="${2:?--require requires a value}"; shift 2;;
+        --mode) MODE="${2:?--mode requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
         *)

package/scripts/tools/verify-citations.sh

@@ -48,7 +48,7 @@ while (($#)); do
     case "$1" in
         -h|--help) USAGE_HELP_MODE=1 usage ;;
         --json) EMIT_JSON=1; shift ;;
-        --tolerance) TOLERANCE="$2"; shift 2 ;;
+        --tolerance) TOLERANCE="${2:?--tolerance requires a value}"; shift 2 ;;
         -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
         *) TRACK_PATHS+=("$1"); shift ;;
     esac
@@ -83,7 +83,7 @@ extract_citations() {
             # bracket expression prematurely terminates a regex literal in
             # POSIX/BSD awk ("nonterminated character class"), though gawk is
             # lenient. The string form is portable across awk implementations.
-            while (match(s, "[A-Za-z0-9_][A-Za-z0-9_./-]*\\.[A-Za-z0-9]+:[0-9]+")) {
+            while (match(s, "[A-Za-z0-9_][A-Za-z0-9_./-]*\\.[A-Za-z0-9]+:[0-9]+(-[0-9]+)?")) {
                 cite = substr(s, RSTART, RLENGTH)
                 printf("%s\t%d\t%s\n", FILENAME, NR, cite)
                 s = substr(s, RSTART + RLENGTH)
@@ -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
@@ -150,7 +130,7 @@ scan_md() {
         # token the `(planned)` annotation owns.
         if echo "$line" | grep -qE '\(planned\)|\[New file'; then
             local paths
-            paths="$(echo "$line" | grep -oE '[A-Za-z][A-Za-z0-9_./-]*\.[A-Za-z]+' | sort -u)"
+            paths="$(echo "$line" | grep -oE '[A-Za-z][A-Za-z0-9_./-]*\.[A-Za-z]+' | sort -u || true)"
             local path_count
             path_count="$(printf '%s\n' "$paths" | grep -c . || true)"
             if (( path_count == 1 )); then

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 .)
@@ -51,8 +53,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --repo) REPO="$2"; shift 2 ;;
-    --plugin-root) PLUGIN_ROOT="$2"; shift 2 ;;
+    --repo) REPO="${2:?--repo requires a value}"; shift 2 ;;
+    --plugin-root) PLUGIN_ROOT="${2:?--plugin-root requires a value}"; shift 2 ;;
     --json) EMIT_JSON=1; shift ;;
     --verbose) VERBOSE=1; shift ;;
     --strict) STRICT=1; shift ;;
@@ -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   │