fix(markdown): seven agents' templates break out of their code blocks

Markdown has no nesting at equal fence length. Inside a ```markdown template, a ```bash line is text, and the example's bare ``` closes the template. Seven agents nest example blocks inside a template that way, so on GitHub the rest of each template renders as headings and prose, and in three of them the last block then runs open to the end of the file: design-ux-architect code from line 414 to EOF ats-validator-architect code from line 307 to EOF master-plan-architect code from line 102 to EOF technical-writer, incident-response-commander, developer-advocate, workflow-architect templates end early, rest renders as markdown The fix for each is the one CommonMark intends: fence the outer template with four backticks so the three-backtick examples stay inside it. Nine outer blocks change; no content does. Nothing caught this because lib.sh's fence_closes_p accepted "```python" as a closing fence. CommonMark allows only whitespace after a closing run, and GitHub renders by that rule. With the old rule the linter and the OpenClaw split read those seven files one way and GitHub another, so each agreed with itself and all three disagreed with what users see. fence_closes_p now requires a bare run, and the OpenClaw split invariant in test-convert-outputs.sh uses the same rule. lint-agents.sh gets two errors, each with the file line number: - a fence line inside an open block that is long enough to close it but carries an info string -- the only way that happens is an attempted nest, and the message says how to fix it - a block that is still open at the end of the file The body loop now reads the file from the line after the frontmatter instead of from $body, which drops every "---" line and so cannot give a line number. It also keeps a last line with no trailing newline; two agents end on a closing fence with none, and without that they read as unclosed. The whole roster lints with 0 errors after the fix; on main the same check reports 18 errors across the seven files. scripts/test-lint-fences.sh covers both errors, the suggested fix, tilde fences, and fence_closes_p directly, and runs in check-tools.yml.
2026-10-13 01:30:05 +00:00 · 2026-09-30 04:37:58 -04:00
parent 765be42358
commit 3d80c07945
12 changed files with 153 additions and 26 deletions
@@ -77,17 +77,27 @@ fence_open_p() {
 }

 # fence_closes_p <line> <open_marker> <open_len> <open_indent> — 0 if <line>
-# closes the open fence (same char, run len >= open, indent <= open); 1
-# otherwise, including non-fence lines (callers need not pre-classify).
+# closes the open fence (same char, run len >= open, indent <= open, nothing
+# but whitespace after the run); 1 otherwise, including non-fence lines
+# (callers need not pre-classify).
+#
+# The "nothing after the run" part is CommonMark's rule, and GitHub renders by
+# it: inside an open ``` block, a "```python" line is content, not a closer
+# and not a nested opener. Accepting it as a closer made these helpers read a
+# ```markdown template holding a ```bash example as two short blocks, while
+# GitHub saw one block that closed at the example's bare ``` — so a ## line
+# the split treated as code rendered as a heading, and the reverse.
 fence_closes_p() {
  local line="$1" open_marker="$2" open_len="$3" open_indent="$4"
  local re='^( {0,3})(`{3,}|~{3,})'
  [[ "$line" =~ $re ]] || return 1
  local close_indent=${#BASH_REMATCH[1]}
  local close_run="${BASH_REMATCH[2]}"
+  local rest="${line:${#BASH_REMATCH[0]}}"
  [[ "${close_run:0:1}" == "$open_marker" ]] || return 1
  (( ${#close_run} >= open_len )) || return 1
  (( close_indent <= open_indent )) || return 1
+  [[ -z "${rest//[[:space:]]/}" ]] || return 1
  return 0
 }

@@ -162,8 +162,15 @@ lint_file() {

  local soul_headers=0
  local agents_headers=0
-  local fence_marker="" fence_len=0 fence_indent=0
-  while IFS= read -r line; do
+  local fence_marker="" fence_len=0 fence_indent=0 fence_line=0
+  # Walk the body from the file itself rather than from $body, so fence
+  # errors can name a real line number. ($body drops every "---" line.)
+  local lineno
+  lineno=$(awk 'NR > 1 && $0 == "---" {print NR; exit}' "$file")
+  # "|| [[ -n $line ]]" keeps a last line that has no trailing newline; several
+  # agents end on a closing fence with none, and dropping it reads as unclosed.
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    lineno=$((lineno + 1))
    # Skip fenced code blocks so ## doc-comment lines (e.g. GDScript `##`)
    # and in-fence markdown headers aren't miscounted (issue #849).
    if [[ -n "$fence_marker" ]]; then
@@ -171,6 +178,17 @@ lint_file() {
        fence_marker=""
        fence_len=0
        fence_indent=0
+      elif fence_open_p "$line" \
+           && [[ "${BASH_REMATCH[2]:0:1}" == "$fence_marker" ]] \
+           && (( ${#BASH_REMATCH[2]} >= fence_len )); then
+        # A fence line long enough to close this block that did not close it
+        # can only be one with an info string: someone nesting ```bash inside
+        # a ```markdown template. Markdown has no nesting at equal length —
+        # GitHub shows that line as text and ends the outer block at the next
+        # bare ```, so the rest of the template renders as a document.
+        echo "ERROR $file:$lineno: '${line}' inside the block opened at line $fence_line does not nest — the next bare ${fence_marker}${fence_marker}${fence_marker} closes the outer block instead"
+        echo "      fence the outer block with a longer run (e.g. ${fence_marker}${fence_marker}${fence_marker}${fence_marker}markdown ... ${fence_marker}${fence_marker}${fence_marker}${fence_marker}) so the inner ones stay inside it"
+        errors=$((errors + 1))
      fi
      continue
    fi
@@ -178,6 +196,7 @@ lint_file() {
      fence_marker="${BASH_REMATCH[2]:0:1}"
      fence_len=${#BASH_REMATCH[2]}
      fence_indent=${#BASH_REMATCH[1]}
+      fence_line=$lineno
      continue
    fi
    if [[ "$line" =~ ^##[[:space:]] ]]; then
@@ -191,7 +210,14 @@ lint_file() {
        agents_headers=$((agents_headers + 1))
      fi
    fi
-  done <<< "$body"
+  done < <(tail -n +"$((lineno + 1))" "$file")
+
+  # An unclosed block runs to the end of the file: on GitHub, and in every
+  # tool the converters feed, everything after the opener renders as code.
+  if [[ -n "$fence_marker" ]]; then
+    echo "ERROR $file:$fence_line: code block is never closed — everything after line $fence_line renders as code"
+    errors=$((errors + 1))
+  fi

  if [[ $soul_headers -eq 0 ]]; then
    echo "WARN  $file: no section headers map to SOUL.md in convert.sh"
@@ -330,7 +330,7 @@ elif not colour_bad:
 # block in half and leaves each file holding a dangling fence, which renders as
 # broken markdown for every user of that integration (#849). So every fenced
 # block in a source must land intact in exactly one of the two files.
-SPLIT_FENCE = re.compile(r"^(`{3,}|~{3,})")
+SPLIT_FENCE = re.compile(r"^(`{3,}|~{3,})(.*)$")

 def body_lines(text):
    """Mirror lib.sh's get_body, including `$(...)`'s trailing-newline strip."""
@@ -352,10 +352,11 @@ def fence_blocks(lines):
        m = SPLIT_FENCE.match(line)
        if not m:
            continue
-        tok = m.group(1)
+        tok, rest = m.group(1), m.group(2)
        if not marker:
            marker, mlen, start = tok[0], len(tok), i
-        elif tok[0] == marker and len(tok) >= mlen:
+        elif tok[0] == marker and len(tok) >= mlen and not rest.strip():
+            # only a bare run closes: "```bash" inside a block is content (lib.sh fence_closes_p)
            res.append((start, i)); marker, mlen, start = "", 0, None
    if marker and start is not None:
        res.append((start, len(lines) - 1))
@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Code fences that GitHub renders differently from what the author meant must
+# fail lint, and the fix the error message suggests must pass it.
+#
+# Markdown has no nesting at equal fence length. Inside a ```markdown template,
+# a ```bash line is text, and the example's closing ``` ends the template, so
+# the rest of it renders as headings and prose. Seven roster agents shipped
+# that way, three of them with the last block left open to the end of the file.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FIXTURE="$(mktemp -d "${TMPDIR:-/tmp}/agency-lint-fences.XXXXXX")"
+trap 'rm -rf "$FIXTURE"' EXIT
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+frontmatter() {
+  cat <<'EOF'
+---
+name: Fence Fixture
+description: Fixture agent for the code-fence lint rules
+color: blue
+---
+## Identity
+Enough words to clear the short-body warning, repeated so the linter has a
+body to read: this fixture exists to check how fenced code blocks are parsed.
+## Core Mission
+Show a template that contains a code example.
+## Critical Rules
+Keep fences balanced.
+EOF
+}
+
+# 1. ```bash inside ```markdown: the inner fence does not nest.
+{ frontmatter; cat <<'EOF'
+### Template
+```markdown
+# Report
+```bash
+npm test
+```
+## Findings
+```
+EOF
+} > "$FIXTURE/nested.md"
+if bash "$SCRIPT_DIR/lint-agents.sh" "$FIXTURE/nested.md" > "$FIXTURE/nested.log" 2>&1; then
+  fail "linter accepted a \`\`\`bash fence nested in a \`\`\`markdown block of the same length"
+fi
+grep -Fq "nested.md:16: '\`\`\`bash' inside the block opened at line 14 does not nest" "$FIXTURE/nested.log" \
+  || { cat "$FIXTURE/nested.log" >&2; fail "nested-fence error is missing or names the wrong lines"; }
+
+# 2. A block left open to the end of the file.
+{ frontmatter; printf '%s\n' '### Layout' '```' 'css/' 'js/'; } > "$FIXTURE/unclosed.md"
+if bash "$SCRIPT_DIR/lint-agents.sh" "$FIXTURE/unclosed.md" > "$FIXTURE/unclosed.log" 2>&1; then
+  fail "linter accepted a code block that is never closed"
+fi
+grep -Fq "unclosed.md:14: code block is never closed" "$FIXTURE/unclosed.log" \
+  || { cat "$FIXTURE/unclosed.log" >&2; fail "unclosed-fence error is missing or names the wrong line"; }
+
+# 3. The fix the message suggests — a longer outer fence — passes, and so do
+#    tilde fences and a shorter run inside a longer block.
+{ frontmatter; cat <<'EOF'
+### Template
+````markdown
+# Report
+```bash
+npm test
+```
+## Findings
+````
+~~~text
+```python is just text in here
+~~~
+EOF
+} > "$FIXTURE/valid.md"
+bash "$SCRIPT_DIR/lint-agents.sh" "$FIXTURE/valid.md" > "$FIXTURE/valid.log" 2>&1 \
+  || { cat "$FIXTURE/valid.log" >&2; fail "linter rejected correctly nested fences"; }
+
+# 4. The helper itself, which the OpenClaw split in convert.sh shares: only a
+#    bare run of the same character, at least as long, closes a block.
+. "$SCRIPT_DIR/lib.sh"
+fence_closes_p '```python' '`' 3 0 && fail "fence_closes_p treated '\`\`\`python' as a closing fence"
+fence_closes_p '```' '`' 3 0       || fail "fence_closes_p rejected a bare closing fence"
+fence_closes_p '````  ' '`' 3 0    || fail "fence_closes_p rejected a longer closing fence with trailing spaces"
+fence_closes_p '```' '`' 4 0       && fail "fence_closes_p let a shorter run close a longer fence"
+
+echo "PASS: nested and unclosed fences are rejected; correctly nested fences pass"