@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/shared/scripts/doflow/bash/render-audit.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# render-audit.sh — projects the orchestrator's own journal into a human-readable audit.md.
+#
+# audit.md is generated, never hand-authored: this script deterministically OVERWRITES it in full
+# from `.doflow/state/orchestration/<slug>.json`'s `history[]` array (WorkflowOrchestrator's own
+# journal — the single source of truth for stage/gate handoffs), one markdown table row per
+# entry. It never appends across runs and never reads the previous audit.md — a stale row can
+# only come from a stale journal, never from this script's own accumulation.
+#
+# Fail-open, matching validate-artifacts.sh's own convention: no active feature, no resolver, or
+# no orchestration run recorded yet are all reported via a note and exit 0 — never a hard error,
+# and no audit.md is written when there is nothing to render.
+#
+# Usage: render-audit.sh [--slug=<slug>] [--json]
+#   No --slug → resolve the active feature via do-paths.sh, exactly like validate-artifacts.sh.
+
+set -uo pipefail
+
+emit_json=false
+slug_override=""
+bad_args=()
+for a in "$@"; do
+  case "$a" in
+    --json)   emit_json=true ;;
+    --slug=*) slug_override="${a#--slug=}" ;;
+    *) bad_args+=("$a") ;;
+  esac
+done
+# An unrecognized argument previously fell through silently — including the space-separated
+# `--slug value` form (only `--slug=value` is accepted), which meant a typo rendered the ACTIVE
+# feature's audit.md instead of the one the caller named, with no signal that anything went wrong.
+if [ "${#bad_args[@]}" -gt 0 ]; then
+  args_joined="${bad_args[*]}"
+  if [ "$emit_json" = true ]; then
+    # Built with jq, not `printf '%s'` interpolation: bad_args is raw argv with no escaping applied
+    # to it, and an argument containing a `"` previously produced a document with a duplicate "ok"
+    # key that JSON resolves to true — inverting this hard failure into an apparent success for any
+    # caller branching on .ok. jq is checked for below the arg-parsing block, not above it, so a
+    # minimally-escaped fallback covers the case this runs before that check does.
+    if command -v jq >/dev/null 2>&1; then
+      jq -nc --arg args "$args_joined" '{"ok":false,"error":"unrecognized-argument","args":$args}' >&2
+    else
+      esc_args=$(printf '%s' "$args_joined" | sed 's/\\/\\\\/g; s/"/\\"/g')
+      printf '{"ok":false,"error":"unrecognized-argument","args":"%s"}\n' "$esc_args" >&2
+    fi
+  else
+    printf 'render-audit: unrecognized argument(s): %s (use --slug=<value>, not --slug <value>)\n' "$args_joined" >&2
+  fi
+  exit 2
+fi
+
+note() {
+  if [ "$emit_json" = true ]; then
+    printf '{"ok":true,"note":"%s","written":false}\n' "$1"
+  else
+    printf 'render-audit: %s (audit.md not written)\n' "$1"
+  fi
+  exit 0
+}
+
+command -v jq >/dev/null 2>&1 || note "jq-absent"
+
+script_dir="$(cd "$(dirname "$0")" && pwd)"
+RESOLVER="$script_dir/do-paths.sh"
+[ -f "$RESOLVER" ] || RESOLVER="${DOFLOW_CONFIG_DIR:+$DOFLOW_CONFIG_DIR/scripts/doflow/bash/do-paths.sh}"
+[ -f "$RESOLVER" ] || note "resolver-absent"
+
+resolver_args=(--json)
+[ -n "$slug_override" ] && resolver_args+=("--slug=$slug_override")
+rc=0; resolved_json=$(bash "$RESOLVER" "${resolver_args[@]}" 2>/dev/null) || rc=$?
+# An unsafe slug is refused, not noted: exit 2 with the resolver's error object (IC-009).
+if [ "$rc" -eq 2 ] && [ "$(printf '%s' "$resolved_json" | jq -r '.error // empty' 2>/dev/null)" = "invalid-slug" ]; then
+  if [ "$emit_json" = true ]; then printf '%s\n' "$resolved_json"; else printf 'render-audit: %s\n' "$(printf '%s' "$resolved_json" | jq -r '.message')" >&2; fi
+  exit 2
+fi
+[ "$rc" -eq 0 ] || note "resolver-error"
+
+repo_root=$(printf '%s' "$resolved_json" | jq -r '.repo_root // empty')
+feature_slug=$(printf '%s' "$resolved_json" | jq -r '.feature_slug // empty')
+audit_rel=$(printf '%s' "$resolved_json" | jq -r '.audit // empty')
+[ -n "$feature_slug" ] || note "no-active-feature"
+
+# WorkflowOrchestrator's own stateDir/runFile convention (workflow-orchestrator.ts):
+#   stateDir = <root>/.doflow/state/orchestration ; runFile = <stateDir>/<taskId>.json
+journal_file="$repo_root/.doflow/state/orchestration/$feature_slug.json"
+[ -f "$journal_file" ] || note "no orchestration run recorded yet"
+
+jq -e '.history | type == "array"' "$journal_file" >/dev/null 2>&1 || note "journal-unreadable"
+
+# Consumed from the resolver's own `audit` field rather than recomputed by hand — do-paths.sh is
+# the single source of truth for this path. Unlike requirement/design/plan, `audit` is set once,
+# unconditionally, before the legacy/structured layout branch, so it never varies by layout — but
+# reading it from the resolver rather than recomputing it here still means a future resolver change
+# has one place to land, not two that can drift apart.
+[ -n "$audit_rel" ] || note "resolver-missing-audit-path"
+audit_file="$repo_root/$audit_rel"
+
+# Render to a temp file first, then move it into place. `>"$audit_file"` truncates the target
+# before the group runs, and with no `-e` a mid-stream jq abort (a malformed or hand-corrupted
+# journal field) would otherwise leave a header-only audit.md behind while this script still
+# reported written:true. Same fail-open philosophy as the notes above: report a clear failure
+# rather than corrupt the target.
+tmp_audit="$(mktemp "${audit_file}.XXXXXX" 2>/dev/null || mktemp)"
+# Every mktemp needs a matching cleanup that runs on the error paths AND on interruption — the
+# explicit `rm -f "$tmp_audit"` below each failure branch does not cover a SIGINT/SIGTERM landing
+# between here and the `mv`, which would otherwise leave a stray `audit.md.XXXXXX` behind inside
+# the feature directory. The trap is a backstop: each failure branch below still removes it
+# immediately on its own path (so a checked exit doesn't wait for the shell to unwind), and this
+# catches everything else. Once the `mv` succeeds, $tmp_audit no longer exists, so a post-mv `rm -f`
+# here is a correctly-silent no-op.
+trap 'rm -f "$tmp_audit"' EXIT
+
+# ── Workflow state diagram (034 IC-006) ───────────────────────────────────────────────────────
+# Drawn from the SAME journal the table below is built from -- `program[]` carries the resolved
+# stage/gate sequence with per-node status, and `cursor` marks where the run actually is. Because
+# both come from one source, the picture cannot disagree with the rows beneath it.
+#
+# Stages and gates only, never individual history entries: that bounds the node count by the
+# workflow definition rather than by how long the run has been going, which is what keeps this
+# inside DIAGRAM_GUIDE.md's own stateDiagram-v2 ceiling.
+#
+# Ids are sanitized (`gate-0` -> `gate_0`) because stateDiagram-v2 reads a hyphen as syntax; the
+# human-readable id is restored via the `state : label` form. A journal with no program[] emits
+# nothing at all rather than an empty fence -- an empty capture here is success, not failure.
+#
+# RENDERED HERE, OUTSIDE the brace group below, and its status checked on the spot. Inside that
+# group it could not be checked at all: `rc=$?` after the group observes only the group's LAST
+# command (the history-table jq), so a failure in this one was invisible -- it emitted three lines,
+# aborted, and left an unterminated ```mermaid fence with the entire history table swallowed inside
+# it, while the script reported written:true and exited 0. The `[ ! -s "$tmp_audit" ]` guard did not
+# catch it either, because the table still wrote bytes. Capturing first means a malformed program[]
+# takes the same clear-failure path every other malformed-journal case already takes, which is what
+# this script's own header promises: report a clear failure rather than corrupt the target.
+if ! state_diagram="$(jq -r '
+    def sid: gsub("-"; "_");
+    (.cursor // -1) as $cur |
+    (.program // []) as $p |
+    if ($p | length) == 0 then empty else
+    "```mermaid",
+    "stateDiagram-v2",
+    "    direction LR",
+    "    [*] --> " + ($p[0].id | sid),
+    ( [range(0; ($p|length)-1)] | .[] | "    " + ($p[.].id|sid) + " --> " + ($p[.+1].id|sid)
+      + (if $p[.].type == "gate" and ($p[.].decision // "") != "" then " : " + $p[.].decision else "" end) ),
+    "    " + ($p[-1].id|sid) + " --> [*]",
+    "",
+    ( [range(0; $p|length)] | .[] as $i | $p[$i] |
+      "    " + (.id|sid) + " : " + .id
+      + (if $i == $cur then " (current)"
+         elif .status == "completed" then " (done)"
+         elif .status == "approved" then " (approved)"
+         elif .status == "rejected" then " (rejected)"
+         else " (pending)" end) ),
+    "```",
+    ""
+    end
+  ' "$journal_file" 2>/dev/null)"; then
+  rm -f "$tmp_audit"
+  if [ "$emit_json" = true ]; then
+    printf '{"ok":false,"error":"state-diagram-render-failed","path":"%s"}\n' "$audit_rel" >&2
+  else
+    printf 'render-audit: failed to render the state diagram for %s (journal program[] may be malformed)\n' "$audit_rel" >&2
+  fi
+  exit 1
+fi
+
+{
+  printf '# Audit Trail: %s\n\n' "$feature_slug"
+  printf '> Generated by `render-audit.sh` from `.doflow/state/orchestration/%s.json`. Do not\n' "$feature_slug"
+  printf '> hand-edit — this file is fully regenerated from the orchestration journal on every run.\n\n'
+  [ -n "$state_diagram" ] && printf '%s\n\n' "$state_diagram"
+  printf '| Date | Stage/Gate | Action | Note / Reason | Flags |\n'
+  printf '|---|---|---|---|---|\n'
+  jq -r '
+    def esc: if . == null then "" else (tostring | gsub("\\\\"; "\\\\") | gsub("\\|"; "\\|") | gsub("\r\n|\n|\r"; " ")) end;
+    .history[] |
+    (.node // "—") as $stage |
+    (if .action == "decide-gate" and (.detail != null and .detail != "")
+       then .action + " (" + .detail + ")"
+       else .action end) as $action |
+    ((.note // "") | esc) as $note_raw |
+    ((.detail // "") | esc) as $detail_raw |
+    (if $note_raw != "" then $note_raw
+     elif .action == "start" and $detail_raw != "" then $detail_raw
+     else "—" end) as $note |
+    (if .forced == true then "⚠ FORCED"
+     elif .backfilled == true then "⚡ BACKFILLED"
+     else "" end) as $flags |
+    "| " + (.at | esc) + " | " + ($stage | esc) + " | " + ($action | esc) + " | " + $note + " | " + $flags + " |"
+  ' "$journal_file"
+} >"$tmp_audit"
+rc=$?
+if [ "$rc" -ne 0 ] || [ ! -s "$tmp_audit" ]; then
+  rm -f "$tmp_audit"
+  if [ "$emit_json" = true ]; then
+    printf '{"ok":false,"error":"render-failed","path":"%s"}\n' "$audit_rel" >&2
+  else
+    printf 'render-audit: failed to render %s (journal may be malformed)\n' "$audit_rel" >&2
+  fi
+  exit 1
+fi
+chmod 644 "$tmp_audit" 2>/dev/null || true
+# Unchecked, an mv failure (target dir missing — do-brainstorm's own state before its step 4
+# mkdir, say — or a permissions problem) left the rendered content stranded in $tmp_audit while
+# this script still reported written:true and exit 0: a false success from the one tool whose job
+# is a trustworthy provenance record.
+mv_err="$(mv "$tmp_audit" "$audit_file" 2>&1)"
+mv_rc=$?
+if [ "$mv_rc" -ne 0 ]; then
+  rm -f "$tmp_audit"
+  if [ "$emit_json" = true ]; then
+    printf '{"ok":false,"error":"move-failed","path":"%s"}\n' "$audit_rel" >&2
+  else
+    printf 'render-audit: failed to write %s (%s)\n' "$audit_rel" "$mv_err" >&2
+  fi
+  exit 1
+fi
+
+if [ "$emit_json" = true ]; then
+  printf '{"ok":true,"written":true,"path":"%s"}\n' "$audit_rel"
+else
+  printf 'render-audit: wrote %s\n' "$audit_rel"
+fi
+exit 0

package/core/shared/scripts/doflow/bash/render-diagrams.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# render-diagrams.sh — renders a chain artifact's fenced mermaid blocks to image files.
+#
+# A FAITHFUL render: the same nodes, the same edges, the same labels. The committed markdown is the
+# only source of truth and is never modified, and no fenced block anywhere carries a theme
+# directive — styling is supplied at render time from assets/mermaid-theme.json, so the source an
+# author wrote is the source a reviewer diffs.
+#
+# Fail-open, matching render-audit.sh's own convention: a missing renderer, no active feature, and
+# an artifact carrying no diagram are each reported via a note and exit 0 — never a hard error. This
+# verb sits OUTSIDE the chain (034 FR-011: user-invoked only, never a stage), so an absent optional
+# capability must never read as a broken run. Exit 1 is reserved for a renderer that ran and failed.
+#
+# Usage: render-diagrams.sh [--slug=<slug>] [--artifact=<path>] [--format=png|svg] [--json]
+#   No --slug     → resolve the active feature via do-paths.sh, exactly like render-audit.sh.
+#   No --artifact → every chain artifact in the feature dir that contains a fenced mermaid block.
+
+set -uo pipefail
+
+emit_json=false
+slug_override=""
+artifact_override=""
+format="png"
+bad_args=()
+for a in "$@"; do
+  case "$a" in
+    --json)       emit_json=true ;;
+    --slug=*)     slug_override="${a#--slug=}" ;;
+    --artifact=*) artifact_override="${a#--artifact=}" ;;
+    --format=*)   format="${a#--format=}" ;;
+    *) bad_args+=("$a") ;;
+  esac
+done
+
+# An unrecognized argument is a hard failure naming it, never a silent fall-through: the
+# space-separated `--slug value` form would otherwise render the ACTIVE feature instead of the one
+# the caller named, with no signal. Same reasoning, same handling, as render-audit.sh.
+if [ "${#bad_args[@]}" -gt 0 ]; then
+  printf 'render-diagrams: unrecognized argument(s): %s\n' "${bad_args[*]}" >&2
+  printf 'usage: render-diagrams.sh [--slug=<slug>] [--artifact=<path>] [--format=png|svg] [--json]\n' >&2
+  exit 2
+fi
+case "$format" in
+  png|svg) ;;
+  *) printf 'render-diagrams: --format must be png or svg, got: %s\n' "$format" >&2; exit 2 ;;
+esac
+
+# Fail-open note: report and exit 0. Nothing downstream may treat an absent capability as failure.
+note() {
+  if [ "$emit_json" = true ]; then
+    if command -v jq >/dev/null 2>&1; then
+      jq -n --arg n "$1" '{ok:true, written:false, note:$n, rendered:[]}'
+    else
+      printf '{"ok":true,"written":false,"note":"%s","rendered":[]}\n' "$1"
+    fi
+  else
+    printf 'render-diagrams: %s (nothing rendered)\n' "$1"
+  fi
+  exit 0
+}
+
+command -v jq >/dev/null 2>&1 || note "jq-absent"
+
+script_dir="$(cd "$(dirname "$0")" && pwd)"
+RESOLVER="$script_dir/do-paths.sh"
+[ -f "$RESOLVER" ] || RESOLVER="${DOFLOW_CONFIG_DIR:+$DOFLOW_CONFIG_DIR/scripts/doflow/bash/do-paths.sh}"
+[ -f "$RESOLVER" ] || note "resolver-absent"
+
+# The theme sits beside this script's own tree, not in the repo being rendered.
+THEME="$script_dir/../assets/mermaid-theme.json"
+
+resolver_args=(--json)
+[ -n "$slug_override" ] && resolver_args+=("--slug=$slug_override")
+rc=0; resolved_json=$(bash "$RESOLVER" "${resolver_args[@]}" 2>/dev/null) || rc=$?
+# An unsafe slug is refused, not noted: exit 2 with the resolver's error object (IC-009).
+if [ "$rc" -eq 2 ] && [ "$(printf '%s' "$resolved_json" | jq -r '.error // empty' 2>/dev/null)" = "invalid-slug" ]; then
+  if [ "$emit_json" = true ]; then printf '%s\n' "$resolved_json"; else printf 'render-diagrams: %s\n' "$(printf '%s' "$resolved_json" | jq -r '.message')" >&2; fi
+  exit 2
+fi
+[ "$rc" -eq 0 ] || note "resolver-error"
+
+repo_root=$(printf '%s' "$resolved_json" | jq -r '.repo_root // empty')
+feature_slug=$(printf '%s' "$resolved_json" | jq -r '.feature_slug // empty')
+feature_dir=$(printf '%s' "$resolved_json" | jq -r '.feature_dir // empty')
+[ -n "$feature_slug" ] || note "no-active-feature"
+[ -n "$feature_dir" ] || note "resolver-missing-feature-dir"
+
+# The renderer is an OPTIONAL dependency, deliberately absent from package.json (034 FR-012): a
+# user who never renders a diagram never pays for a headless browser download. Its absence is
+# reported with the way to get it, and is not a failure.
+command -v mmdc >/dev/null 2>&1 || note "mermaid renderer not found. Install with: npm install -g @mermaid-js/mermaid-cli (or run: doflow doctor)"
+
+# The theme is REQUIRED, not best-effort (034 FR-014): the render must apply the diagram-design
+# roles, so an absent asset is reported rather than silently producing default-styled output. It
+# fails open exactly as the absent renderer above does -- a note and exit 0 -- because this verb
+# sits outside the chain and a missing shipped asset is a broken install, not a broken run. The
+# earlier form appended `-c` only when the file happened to exist, which meant a reinstall gone
+# wrong rendered unthemed images and reported ok:true with failures:0 and nothing on stderr.
+[ -f "$THEME" ] || note "theme asset missing at $THEME. The render would not apply the DoFlow diagram theme, so it was not attempted. Reinstall the scripts tree: npx @khoavu882/doflow install"
+
+out_dir="$repo_root/$feature_dir/design/diagrams"
+
+# Collect the artifacts to scan. A named --artifact wins; otherwise every markdown file in the
+# feature dir, in a stable order so block indices are reproducible across runs.
+artifacts=()
+if [ -n "$artifact_override" ]; then
+  candidate="$artifact_override"
+  [ -f "$candidate" ] || candidate="$repo_root/$artifact_override"
+  [ -f "$candidate" ] || { printf 'render-diagrams: no such artifact: %s\n' "$artifact_override" >&2; exit 2; }
+  artifacts+=("$candidate")
+else
+  while IFS= read -r f; do artifacts+=("$f"); done < <(find "$repo_root/$feature_dir" -type f -name '*.md' -not -path '*/diagrams/*' | sort)
+fi
+[ "${#artifacts[@]}" -gt 0 ] || note "no markdown artifacts found under $feature_dir"
+
+tmpdir="$(mktemp -d 2>/dev/null)" || note "mktemp-failed"
+trap 'rm -rf "$tmpdir"' EXIT
+
+rendered=()
+failures=0
+total_blocks=0
+
+for artifact in "${artifacts[@]}"; do
+  stem="$(basename "$artifact")"; stem="${stem%.md}"
+
+  # Extract each fenced mermaid block to its own file, numbered from 01 in DOCUMENT ORDER. Index,
+  # not heading text, is the identity: a heading is free prose that can change without the diagram
+  # changing, which would silently rename an output file.
+  count=$(awk -v outdir="$tmpdir" -v stem="$stem" '
+    /^[[:space:]]*```mermaid[[:space:]]*$/ && !inblock { inblock=1; n++; f=sprintf("%s/%s-%02d.mmd", outdir, stem, n); next }
+    inblock && /^[[:space:]]*```[[:space:]]*$/ { inblock=0; close(f); next }
+    inblock { print >> f }
+    END { print n+0 }
+  ' "$artifact")
+
+  [ "$count" -gt 0 ] 2>/dev/null || continue
+  total_blocks=$((total_blocks + count))
+  mkdir -p "$out_dir" || note "cannot create $out_dir"
+
+  i=1
+  while [ "$i" -le "$count" ]; do
+    nn=$(printf '%02d' "$i")
+    src="$tmpdir/$stem-$nn.mmd"
+    dest="$out_dir/$stem-$nn.$format"
+    # -s 2 renders PNG at twice device scale so it stays sharp projected; ignored for svg.
+    mmdc_args=(-i "$src" -o "$dest" -b "#f5f5f5" -c "$THEME")
+    [ "$format" = "png" ] && mmdc_args+=(-s 2)
+    if mmdc "${mmdc_args[@]}" >/dev/null 2>&1; then
+      rendered+=("$feature_dir/design/diagrams/$stem-$nn.$format")
+    else
+      failures=$((failures + 1))
+      printf 'render-diagrams: renderer failed on %s block %s\n' "$(basename "$artifact")" "$nn" >&2
+    fi
+    i=$((i + 1))
+  done
+done
+
+[ "$total_blocks" -gt 0 ] || note "no fenced mermaid block found in the artifacts scanned"
+
+# The output directory excludes its own contents, in any host project, whether or not that project
+# ignores agent-docs/. `!.gitignore` keeps the rule itself trackable so it becomes durable once
+# committed. The installer manages no ignore rules, so the verb owns this.
+if [ -d "$out_dir" ] && [ ! -f "$out_dir/.gitignore" ]; then
+  printf '*\n!.gitignore\n' > "$out_dir/.gitignore"
+fi
+
+if [ "$emit_json" = true ]; then
+  printf '%s\n' "${rendered[@]:-}" | jq -R . | jq -s \
+    --argjson failures "$failures" --argjson blocks "$total_blocks" --arg dir "$feature_dir/design/diagrams" \
+    'map(select(length > 0)) | {ok: ($failures == 0), written: (length > 0), dir: $dir, blocks: $blocks, failures: $failures, rendered: .}'
+else
+  printf 'render-diagrams: %s of %s block(s) rendered into %s\n' "${#rendered[@]}" "$total_blocks" "$feature_dir/design/diagrams"
+  for r in "${rendered[@]:-}"; do [ -n "$r" ] && printf '  %s\n' "$r"; done
+fi
+
+[ "$failures" -eq 0 ] || exit 1
+exit 0

package/core/shared/scripts/doflow/bash/render-puml.sh

@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+# render-puml.sh — renders a feature's authored PlantUML sources and projects them into its artifact.
+#
+# ONE verb doing BOTH derived views, deliberately (035 design R6): reading the source once means the
+# committed image and the generated inline block cannot come from different revisions of it. Two
+# verbs could, and that drift is what this whole feature exists to remove.
+#
+# Fail-open, matching render-audit.sh and render-diagrams.sh: no active feature, no design/c4/
+# directory, and no renderer are each reported via a note and exit 0. Authoring C4 in PlantUML is
+# OPT-IN per feature, so a feature without design/c4/ is not a broken feature -- it is the ordinary
+# case, and this verb must say so rather than fail.
+#
+# Writes ONLY into <feature dir>/design/c4/ and one delimited region of one artifact. It never
+# touches design/diagrams/, which is feature 034's ignored render output (035 IC-005).
+#
+# Usage: render-puml.sh [--slug=<slug>] [--check] [--json]
+
+set -uo pipefail
+
+emit_json=false
+check_only=false
+slug_override=""
+bad_args=()
+for a in "$@"; do
+  case "$a" in
+    --json)   emit_json=true ;;
+    --check)  check_only=true ;;
+    --slug=*) slug_override="${a#--slug=}" ;;
+    *) bad_args+=("$a") ;;
+  esac
+done
+
+if [ "${#bad_args[@]}" -gt 0 ]; then
+  printf 'render-puml: unrecognized argument(s): %s\n' "${bad_args[*]}" >&2
+  printf 'usage: render-puml.sh [--slug=<slug>] [--check] [--json]\n' >&2
+  exit 2
+fi
+
+note() {
+  if [ "$emit_json" = true ]; then
+    if command -v jq >/dev/null 2>&1; then jq -n --arg n "$1" '{ok:true, written:false, note:$n, rendered:[]}'
+    else printf '{"ok":true,"written":false,"note":"%s","rendered":[]}\n' "$1"; fi
+  else
+    printf 'render-puml: %s (nothing rendered)\n' "$1"
+  fi
+  exit 0
+}
+
+command -v jq >/dev/null 2>&1 || note "jq-absent"
+
+script_dir="$(cd "$(dirname "$0")" && pwd)"
+RESOLVER="$script_dir/do-paths.sh"
+[ -f "$RESOLVER" ] || RESOLVER="${DOFLOW_CONFIG_DIR:-$HOME/.doflow}/scripts/doflow/bash/do-paths.sh"
+[ -f "$RESOLVER" ] || note "resolver-absent"
+# Resolved after repo_root below, since the runtime sits beside the repo root in a checkout and
+# under <config>/runtime/ in an install -- the resolver is the only thing that knows which.
+
+resolver_args=(--json)
+[ -n "$slug_override" ] && resolver_args+=("--slug=$slug_override")
+rc=0; resolved_json=$(bash "$RESOLVER" "${resolver_args[@]}" 2>/dev/null) || rc=$?
+# An unsafe slug is refused, not noted: exit 2 with the resolver's error object (IC-009).
+if [ "$rc" -eq 2 ] && [ "$(printf '%s' "$resolved_json" | jq -r '.error // empty' 2>/dev/null)" = "invalid-slug" ]; then
+  if [ "$emit_json" = true ]; then printf '%s\n' "$resolved_json"; else printf 'render-puml: %s\n' "$(printf '%s' "$resolved_json" | jq -r '.message')" >&2; fi
+  exit 2
+fi
+[ "$rc" -eq 0 ] || note "resolver-error"
+
+repo_root=$(printf '%s' "$resolved_json" | jq -r '.repo_root // empty')
+feature_slug=$(printf '%s' "$resolved_json" | jq -r '.feature_slug // empty')
+feature_dir=$(printf '%s' "$resolved_json" | jq -r '.feature_dir // empty')
+
+# The projector lives in the JS runtime, not beside the helpers: G12 keeps this repo to one runtime
+# implementation, and Python in core/ is how a shadow tree grew the first time, one individually
+# defensible module at a time. render-audit.sh already shells out to node for the same reason.
+PROJECTOR="$repo_root/src/runtime/c4-project.ts"
+[ -f "$PROJECTOR" ] || PROJECTOR="${DOFLOW_CONFIG_DIR:-$HOME/.doflow}/runtime/src/runtime/c4-project.ts"
+design_rel=$(printf '%s' "$resolved_json" | jq -r '.design // empty')
+[ -n "$feature_slug" ] || note "no-active-feature"
+[ -n "$feature_dir" ] || note "resolver-missing-feature-dir"
+
+src_dir="$repo_root/$feature_dir/design/c4"
+# Authoring C4 in PlantUML is opt-in. No directory is the ordinary case, not a failure.
+[ -d "$src_dir" ] || note "no design/c4/ directory in $feature_dir — authoring C4 in PlantUML is opt-in, so there is nothing to render"
+
+sources=()
+while IFS= read -r f; do sources+=("$f"); done < <(find "$src_dir" -maxdepth 1 -type f -name '*.puml' | sort)
+[ "${#sources[@]}" -gt 0 ] || note "no .puml source found in $feature_dir/design/c4"
+
+# Which source feeds design.md's inline block: container when present, else context. Named once so
+# --check and the render loop cannot disagree about which source the block is supposed to match.
+block_source_for() {
+  local pick="" stem
+  for f in "$@"; do
+    stem="$(basename "${f%.puml}")"
+    if [ "$stem" = "container" ]; then pick="$f"; fi
+    if [ -z "$pick" ] && [ "$stem" = "context" ]; then pick="$f"; fi
+  done
+  printf '%s' "$pick"
+}
+
+short_hash() { node -e 'const c=require("node:crypto"),f=require("node:fs");process.stdout.write(c.createHash("sha256").update(f.readFileSync(process.argv[1])).digest("hex").slice(0,12))' "$1"; }
+
+# ── --check: re-hash and report, rendering and writing nothing (035 IC-004) ──────────────────────
+if [ "$check_only" = true ]; then
+  stale=()
+  for src in "${sources[@]}"; do
+    want="$(short_hash "$src")"
+    have=""
+    [ -f "${src%.puml}.sha" ] && have="$(cat "${src%.puml}.sha")"
+    [ "$want" = "$have" ] || stale+=("$(basename "$src")")
+  done
+  # IC-004 records the revision in BOTH derived outputs, so checking only the .sha sibling checked
+  # only the image. The sibling is written inside the renderer-success branch below; the inline
+  # block is written by a separate branch that an absent marker pair can skip. They drift apart, and
+  # a check that reads one of them reports the other as current without ever having looked at it.
+  block_src="$(block_source_for "${sources[@]}")"
+  if [ -n "$block_src" ] && [ -n "$design_rel" ] && [ -f "$repo_root/$design_rel" ]; then
+    want="$(short_hash "$block_src")"
+    have="$(sed -n 's/.*source-hash: \([0-9a-f]*\).*/\1/p' "$repo_root/$design_rel" | head -1)"
+    [ "$want" = "$have" ] || stale+=("$(basename "$block_src") -> inline block in $design_rel")
+  fi
+  if [ "$emit_json" = true ]; then
+    printf '%s\n' "${stale[@]:-}" | jq -R . | jq -s \
+      --argjson ok "$([ "${#stale[@]}" -eq 0 ] && echo true || echo false)" \
+      'map(select(length>0)) | {ok: $ok, checked:true, stale:.}'
+  else
+    if [ "${#stale[@]}" -eq 0 ]; then printf 'render-puml: every derived output matches its source\n'
+    else printf 'render-puml: stale against their source: %s\n' "${stale[*]}"; fi
+  fi
+  [ "${#stale[@]}" -eq 0 ] || exit 1
+  exit 0
+fi
+
+have_renderer=true
+command -v plantuml >/dev/null 2>&1 || have_renderer=false
+
+block_src="$(block_source_for "${sources[@]}")"
+rendered=(); failures=0; projected=""
+for src in "${sources[@]}"; do
+  stem="$(basename "${src%.puml}")"
+  digest="$(short_hash "$src")"
+
+  if [ "$have_renderer" = true ]; then
+    if plantuml -tpng -o "$src_dir" "$src" >/dev/null 2>&1; then
+      printf '%s\n' "$digest" > "${src%.puml}.sha"
+      rendered+=("$feature_dir/design/c4/$stem.png")
+    else
+      failures=$((failures + 1))
+      printf 'render-puml: renderer failed on %s\n' "$stem.puml" >&2
+    fi
+  fi
+
+  # One source feeds design.md §2's inline block; the others render only to images.
+  if [ "$src" = "$block_src" ]; then
+    # stdout only is the block: the splice writes it into authored prose, so anything the projector
+    # (or Node) prints on stderr, an ExperimentalWarning for one, must never become part of it.
+    proj_err="$(mktemp)" || note "mktemp-failed"
+    if ! block="$(node "$PROJECTOR" "$src" 2>"$proj_err")"; then
+      printf 'render-puml: %s%s\n' "$(cat "$proj_err")" "$block" >&2
+      rm -f "$proj_err"
+      exit 1
+    fi
+    [ -s "$proj_err" ] && cat "$proj_err" >&2
+    rm -f "$proj_err"
+    projected="$block"
+  fi
+done
+
+[ "$have_renderer" = true ] || note "PlantUML not found. Run 'doflow tools' for the install command registered for this machine (on Homebrew: brew install plantuml), or 'doflow doctor'. The sources were left unrendered."
+
+# ── Replace the delimited region of the artifact (035 IC-004, RK3) ───────────────────────────────
+# The one operation here that can destroy authored prose. Two guards: an artifact whose markers are
+# absent is REPORTED and left untouched rather than repaired by guess, and the rewrite goes through
+# a temp file moved into place -- the same pattern render-audit.sh uses, for the same reason.
+block_written=false
+if [ -n "$projected" ] && [ -n "$design_rel" ] && [ -f "$repo_root/$design_rel" ]; then
+  target="$repo_root/$design_rel"
+  if grep -q '<!-- generated from' "$target" && grep -q '<!-- end generated -->' "$target"; then
+    tmp="$(mktemp "${target}.XXXXXX")" || note "mktemp-failed"
+    trap 'rm -f "$tmp"' EXIT
+    # Two corrections a review found here. The end offset added the CLOSE marker's length PLUS a
+    # newline unconditionally, so whenever the marker was not followed by one it ate the next
+    # character instead -- and because the character it ate first was the newline, every later run
+    # ate another. It had already demoted this feature's own "### C4 Level 3" heading to "##" and
+    # glued it to the marker. And CLOSE is now searched FROM start, so a close marker sitting before
+    # the open one reads as absent rather than duplicating everything between them.
+    if node -e '
+      const fs = require("node:fs");
+      const [target, tmp, block] = process.argv.slice(1);
+      const OPEN = "<!-- generated from";
+      const CLOSE = "<!-- end generated -->";
+      const text = fs.readFileSync(target, "utf8");
+      const start = text.indexOf(OPEN);
+      const closeAt = start === -1 ? -1 : text.indexOf(CLOSE, start);
+      if (closeAt === -1) {
+        process.stderr.write("generated-block markers are absent or out of order\n");
+        process.exit(1);
+      }
+      const afterClose = closeAt + CLOSE.length;
+      const end = afterClose + (text[afterClose] === "\n" ? 1 : 0);
+      fs.writeFileSync(tmp, text.slice(0, start) + block + text.slice(end));
+    ' "$target" "$tmp" "$projected" && [ -s "$tmp" ]; then
+      mv "$tmp" "$target"; block_written=true
+    else
+      rm -f "$tmp"
+      failures=$((failures + 1))
+      printf 'render-puml: rewriting %s failed; it was left untouched\n' "$design_rel" >&2
+    fi
+  else
+    printf 'render-puml: %s carries no generated-block markers; it was left untouched\n' "$design_rel" >&2
+  fi
+fi
+
+if [ "$emit_json" = true ]; then
+  printf '%s\n' "${rendered[@]:-}" | jq -R . | jq -s \
+    --argjson failures "$failures" --arg dir "$feature_dir/design/c4" --argjson block "$([ "$block_written" = true ] && echo true || echo false)" \
+    'map(select(length>0)) | {ok: ($failures==0), written: (length>0), dir: $dir, blockWritten: $block, failures: $failures, rendered: .}'
+else
+  printf 'render-puml: %s source(s) rendered into %s; inline block %s\n' "${#rendered[@]}" "$feature_dir/design/c4" "$([ "$block_written" = true ] && echo written || echo 'not written')"
+fi
+
+[ "$failures" -eq 0 ] || exit 1
+exit 0