@friedbotstudio/create-baseline 0.1.0

package/obj/template/.claude/hooks/lint_runner.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Lint Runner hook — PostToolUse(Edit|Write|MultiEdit)
+#
+# Runs the project-configured lint command against the changed file.
+# Guide-mode behaviour matches test_runner.sh: until `.claude/project.json`
+# is configured, emits guidance rather than failing.
+
+# shellcheck source=./lib/common.sh
+. "${BASH_SOURCE[0]%/*}/lib/common.sh"
+read_payload
+
+TOOL="$(payload_get .tool_name)"
+case "$TOOL" in
+  Edit|Write|MultiEdit) ;;
+  *) emit_allow ;;
+esac
+
+FILE="$(payload_get .tool_input.file_path)"
+[ -n "$FILE" ] || emit_allow
+rel="${FILE#$CLAUDE_PROJECT_ROOT/}"
+
+case "$rel" in
+  *.md|*.json|*.yaml|*.yml|*.toml|*.txt|docs/*|.claude/*|.config/*) emit_allow ;;
+esac
+
+configured="$(project_get .configured)"
+cmd="$(project_get .lint.cmd)"
+
+if [ "$configured" != "True" ] && [ "$configured" != "true" ]; then
+  emit_info "Lint Runner: .claude/project.json is not configured yet. Run \`/init-project\` to declare the lint command."
+  emit_allow
+fi
+
+if [ -z "$cmd" ] || [ "$cmd" = "None" ]; then
+  emit_info "Lint Runner: no .lint.cmd set in .claude/project.json. Skipping lint for '$rel'."
+  emit_allow
+fi
+
+timeout_s="$(project_get .lint.timeout_seconds)"
+[ -z "$timeout_s" ] && timeout_s=60
+
+final="${cmd//\{file\}/$rel}"
+
+emit_info "Lint Runner: running \`$final\` (timeout ${timeout_s}s)"
+out="$(cd "$CLAUDE_PROJECT_ROOT" && timeout "${timeout_s}s" bash -lc "$final" 2>&1)"
+rc=$?
+if [ $rc -ne 0 ]; then
+  log_line lint_runner "FAIL rc=$rc cmd=$final"
+  emit_info "Lint Runner: FAILED (exit $rc) — output:"
+  emit_info "$out"
+  exit 2
+fi
+
+log_line lint_runner "PASS cmd=$final"
+emit_allow

package/obj/template/.claude/hooks/memory_pre_compact.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Memory PreCompact — PreCompact event
+#
+# Fires before context compaction (manual /compact or auto). At this point
+# the full transcript is still on disk; we walk it and write a continuity
+# snapshot to .claude/memory/_resume.md. The next SessionStart (source:
+# compact) re-injects that snapshot so the model knows where it left off.
+#
+# This hook NEVER blocks compaction. Snapshotting must be best-effort:
+# a transcript-walk failure should not punish the user.
+#
+# Per docs: PreCompact stdout is NOT injected into context (only logged).
+# So all useful output goes to disk; this hook prints nothing on stdout.
+
+# shellcheck source=./lib/common.sh
+. "${BASH_SOURCE[0]%/*}/lib/common.sh"
+read_payload
+
+TRANSCRIPT="$(payload_get .transcript_path)"
+TRIGGER="$(payload_get .trigger)"
+[ -n "$TRIGGER" ] || TRIGGER="auto"
+
+# If we can't find the transcript, log and bail — never fail compaction.
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+  log_line memory_pre_compact "no transcript path; skipped (trigger=$TRIGGER)"
+  exit 0
+fi
+
+MEM_DIR="$CLAUDE_DOTDIR/memory"
+[ -d "$MEM_DIR" ] || { log_line memory_pre_compact "memory dir missing; skipped"; exit 0; }
+
+python3 "$CLAUDE_DOTDIR/hooks/lib/resume_writer.py" \
+  "$TRANSCRIPT" "$CLAUDE_PROJECT_ROOT" "pre-compact" 2>>"$LOG_DIR/memory_pre_compact.log" || true
+
+log_line memory_pre_compact "wrote _resume.md (trigger=$TRIGGER)"
+exit 0

package/obj/template/.claude/hooks/memory_session_start.sh

@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+# Memory Session Start — SessionStart
+#
+# At every session start, scans .claude/memory/*.md and emits a compact index
+# into Claude's startup context: per-file entry counts, stale-entry counts,
+# and a pending-flush nag if _pending.md has unreviewed candidates.
+#
+# Output format: structured `additionalContext` JSON so Claude Code injects
+# the index directly into the startup prompt. Output kept under ~2KB; the
+# canonical files load on first relevant skill invocation.
+
+# shellcheck source=./lib/common.sh
+. "${BASH_SOURCE[0]%/*}/lib/common.sh"
+read_payload
+
+# Marker cleanup — remove stale .harness_active from a prior session.
+# Runs BEFORE the memory-dir check so cleanup happens regardless of memory state.
+# Cross-session ghost prevention: the harness_continuation Stop hook reads this
+# marker as Rung 2; without this cleanup, a leftover marker from a prior session
+# would let yesterday's state: continue re-fire on today's first turn-end.
+MARKER="$CLAUDE_DOTDIR/state/.harness_active"
+if [ -f "$MARKER" ]; then
+  MARKER_SLUG="$(head -1 "$MARKER" 2>/dev/null)"
+  rm -f "$MARKER"
+  mkdir -p "$LOG_DIR"
+  printf '%s  INFO  removed stale .harness_active (slug=%s)\n' \
+    "$(date -u +%FT%TZ)" "$MARKER_SLUG" >> "$LOG_DIR/harness_continuation.log"
+fi
+
+MEM_DIR="$CLAUDE_DOTDIR/memory"
+
+# If the memory directory doesn't exist (fresh repo, pre-init), do nothing.
+[ -d "$MEM_DIR" ] || exit 0
+
+# How the session started — drives the framing line for the resume snapshot.
+SESSION_SOURCE="$(payload_get .source)"
+[ -n "$SESSION_SOURCE" ] || SESSION_SOURCE="startup"
+
+context="$(MEM_DIR="$MEM_DIR" CLAUDE_PROJECT_ROOT="$CLAUDE_PROJECT_ROOT" SESSION_SOURCE="$SESSION_SOURCE" python3 <<'PY'
+import json, os, re, subprocess
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+mem_dir = Path(os.environ['MEM_DIR'])
+root = Path(os.environ['CLAUDE_PROJECT_ROOT'])
+
+# Resolve the current HEAD; if not a git repo, leave HEAD blank (skill cite-then-verify still works).
+try:
+    head = subprocess.check_output(
+        ['git', '-C', str(root), 'rev-parse', '--short', 'HEAD'],
+        stderr=subprocess.DEVNULL, text=True,
+    ).strip()
+except Exception:
+    head = ''
+
+# Files in canonical order. _pending.md handled separately.
+canonical = ['landmarks', 'libraries', 'decisions', 'landmines', 'conventions', 'pending-questions']
+PENDING_FILE = 'pending-questions'
+STALE_COMMITS = 30
+STALE_DAYS = 30  # non-git fallback threshold
+
+
+def _field(block, name):
+    m = re.search(rf'(?m)^\s*-\s*{re.escape(name)}\s*:\s*(.+?)\s*$', block, re.IGNORECASE)
+    return m.group(1).strip() if m else None
+
+
+def _commit_distance(stamp):
+    try:
+        d = subprocess.check_output(
+            ['git', '-C', str(root), 'rev-list', '--count', f'{stamp}..HEAD'],
+            stderr=subprocess.DEVNULL, text=True,
+        ).strip()
+        return int(d) if d.isdigit() else None
+    except Exception:
+        return None
+
+
+def _days_since(iso):
+    try:
+        d = datetime.strptime(iso, '%Y-%m-%d').date()
+        return (date.today() - d).days
+    except Exception:
+        return None
+
+
+def _split_blocks(body):
+    parts = re.split(r'(?m)^(##\s+\S.*)$', body)
+    out = []
+    for i in range(1, len(parts), 2):
+        heading = parts[i]
+        tail = parts[i + 1] if i + 1 < len(parts) else ''
+        key = heading[2:].strip().split()[0] if heading[2:].strip() else ''
+        out.append((key, heading + tail))
+    return out
+
+
+def _is_stale(block, name):
+    closure_field = 'resolved-at' if name == PENDING_FILE else 'superseded-at'
+    if _field(block, closure_field):
+        return False
+    stamp = _field(block, 'verified-at')
+    if head and stamp and stamp != 'HEAD':
+        dist = _commit_distance(stamp)
+        return dist is None or dist >= STALE_COMMITS
+    if not head:
+        days = _days_since(_field(block, 'last-touched') or '')
+        return days is not None and days >= STALE_DAYS
+    return False
+
+
+rows = []
+total_entries = 0
+total_stale = 0
+stale_records = []  # (file_name, key, last_touched) for the rendered block
+
+for name in canonical:
+    p = mem_dir / f'{name}.md'
+    if not p.is_file():
+        rows.append((name, 0, 0, 'missing'))
+        continue
+    text = p.read_text(encoding='utf-8', errors='replace')
+    body = text.split('---', 2)[-1] if text.startswith('---') else text
+    blocks = _split_blocks(body)
+    n = len(blocks)
+    total_entries += n
+    stale = 0
+    for key, blk in blocks:
+        if not _is_stale(blk, name):
+            continue
+        stale += 1
+        stale_records.append((name, key, _field(blk, 'last-touched') or ''))
+    total_stale += stale
+    rows.append((name, n, stale, 'ok'))
+
+# Pending candidates: count `## CANDIDATE:` entries in _pending.md body.
+pending_path = mem_dir / '_pending.md'
+pending_count = 0
+if pending_path.is_file():
+    body = pending_path.read_text(encoding='utf-8', errors='replace').split('---', 2)[-1]
+    pending_count = len(re.findall(r'(?m)^##\s+CANDIDATE\b', body))
+
+# Compose the context block.
+lines = [
+    '## Project memory — index (.claude/memory/)',
+    '',
+    f'HEAD: `{head or "n/a"}`  ·  total entries: {total_entries}  ·  stale (>=30 commits old): {total_stale}',
+    '',
+    '| File | Entries | Stale | Status |',
+    '|---|---:|---:|---|',
+]
+for name, n, stale, status in rows:
+    lines.append(f'| `{name}.md` | {n} | {stale} | {status} |')
+
+if stale_records:
+    stale_records.sort(key=lambda r: (r[2] or '', f'{r[0]}:{r[1]}'))
+    top = stale_records[:5]
+    overflow = len(stale_records) - 5
+    lines.append('')
+    lines.append('## Stale entries')
+    lines.append('')
+    for fname, key, last in top:
+        last_part = f' — last-touched {last}' if last else ''
+        lines.append(f'- `{fname}.md` `{key}`{last_part}')
+    if overflow > 0:
+        lines.append(f'… and {overflow} more')
+
+lines.append('')
+
+if pending_count > 0:
+    lines.append(
+        f'**{pending_count} candidate{"" if pending_count == 1 else "s"} pending in `_pending.md`** — '
+        'run `/memory-flush` to review and commit keepers before starting workflow phases.'
+    )
+else:
+    lines.append('No pending memory candidates.')
+
+lines.append('')
+lines.append(
+    'Files are read on demand by the relevant skill (scout reads landmarks, research reads libraries, etc.). '
+    'Every cited entry is re-verified before use; failed verifications are corrected or deleted in the same run. '
+    'See `.claude/memory/README.md` for the entry shape and self-healing rules.'
+)
+
+out = '\n'.join(lines)
+# Cap the index portion at ~2KB so the resume snapshot has room.
+if len(out) > 2048:
+    out = out[:2000] + '\n…(index truncated)'
+
+# Resume snapshot — only injected when present and reasonably fresh.
+# Source-aware framing tells the model why it's seeing this and what to do.
+src = os.environ.get('SESSION_SOURCE', 'startup')
+framings = {
+    'compact':  '↻ Resuming after compaction. Last captured state below — pick up from here.',
+    'clear':    '↻ Continuity from prior session. The user just `/clear`\'d; here is where things stood.',
+    'resume':   '↻ Session resumed. Last captured state below.',
+    'startup':  '↻ Prior session left this snapshot. If still relevant, pick up from here.',
+}
+framing = framings.get(src, framings['startup'])
+
+resume_path = mem_dir / '_resume.md'
+if resume_path.is_file():
+    try:
+        raw = resume_path.read_text(encoding='utf-8', errors='replace')
+        # Skip frontmatter (between leading --- markers) — keep just the body.
+        body = raw
+        if raw.startswith('---'):
+            parts = raw.split('---', 2)
+            if len(parts) == 3:
+                body = parts[2].lstrip('\n')
+        # Freshness gate: only inject if file modified <= 7 days ago.
+        mtime = datetime.fromtimestamp(resume_path.stat().st_mtime, tz=timezone.utc)
+        age_days = (datetime.now(timezone.utc) - mtime).days
+        if age_days <= 7 and body.strip():
+            # Total cap ~9.5KB to stay well under the 10KB additionalContext limit.
+            budget = 9500 - len(out) - len(framing) - 80
+            if budget > 500:
+                if len(body) > budget:
+                    body = body[:budget].rstrip() + '\n\n…(snapshot truncated)'
+                out = (
+                    out
+                    + '\n\n---\n\n'
+                    + framing
+                    + f' (snapshot age: {age_days}d)\n\n'
+                    + body
+                )
+    except Exception:
+        pass
+
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'SessionStart',
+        'additionalContext': out,
+    },
+}))
+PY
+)"
+
+# If python emitted nothing (memory dir empty / parse failure), exit silently.
+[ -n "$context" ] || exit 0
+
+printf '%s\n' "$context"
+log_line memory_session_start "emitted memory index"
+exit 0

package/obj/template/.claude/hooks/memory_stop.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# Memory Stop — Stop event
+#
+# Fires once per assistant turn (end of a Claude response). Reads the
+# transcript file (a JSONL where each line is one event), extracts patterns
+# that look like memory candidates, and appends them to
+# .claude/memory/_pending.md for later curation via /memory-flush.
+#
+# This hook is a PASSIVE COLLECTOR. It never writes to canonical memory
+# files — only to the gitignored body of _pending.md. Claude curates
+# candidates in main context via /memory-flush.
+#
+# Patterns extracted:
+#   - Edit/Write/MultiEdit on source files → landmark candidate
+#   - context7 MCP queries (resolve-library-id / query-docs) → library candidate
+#   - Bash 'rg'/'grep'/'git' searches over source dirs → potential landmark/landmine
+#   - Tool calls that touched .claude/memory/* → no-op (don't candidate-extract on memory writes)
+
+# shellcheck source=./lib/common.sh
+. "${BASH_SOURCE[0]%/*}/lib/common.sh"
+read_payload
+
+TRANSCRIPT="$(payload_get .transcript_path)"
+[ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ] || exit 0
+
+MEM_DIR="$CLAUDE_DOTDIR/memory"
+PENDING="$MEM_DIR/_pending.md"
+[ -f "$PENDING" ] || exit 0
+
+# Extract candidates with python; never fail the hook (it's advisory).
+TRANSCRIPT="$TRANSCRIPT" PENDING="$PENDING" python3 <<'PY' || true
+import json, os, re, sys, time
+from pathlib import Path
+from datetime import datetime, timezone
+
+transcript = Path(os.environ['TRANSCRIPT'])
+pending = Path(os.environ['PENDING'])
+
+# Load existing pending body to avoid re-emitting duplicates within the session.
+existing = pending.read_text(encoding='utf-8', errors='replace')
+existing_keys = set(re.findall(r'(?m)^##\s+CANDIDATE:\s*(\S+)', existing))
+
+candidates = []  # (key, category, body_lines)
+
+# Source-dir prefixes that are interesting for landmark candidates.
+SRC_PREFIXES = ('src/', 'lib/', 'app/', 'pkg/', 'internal/', 'cmd/', '.claude/hooks/', '.claude/skills/')
+SKIP_PREFIXES = ('.claude/memory/', '.claude/state/', 'docs/scout/', 'docs/research/', 'docs/intake/',
+                 'docs/specs/', 'docs/brd/', 'docs/rca/', 'docs/security/', 'docs/archive/')
+
+def is_source(path: str) -> bool:
+    if not isinstance(path, str) or not path:
+        return False
+    if any(path.startswith(p) for p in SKIP_PREFIXES):
+        return False
+    if any(path.startswith(p) for p in SRC_PREFIXES):
+        return True
+    return False
+
+# Track per-path edit counts so we only candidate paths touched ≥1 time
+# (loose threshold; the curator decides what's worth keeping).
+path_touches = {}  # path -> count
+lib_queries = []  # list of dicts {library, topic}
+
+# Walk the transcript JSONL.
+try:
+    with transcript.open('r', encoding='utf-8', errors='replace') as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                ev = json.loads(line)
+            except Exception:
+                continue
+            # Most relevant: assistant tool_use blocks.
+            msg = ev.get('message') or ev
+            if not isinstance(msg, dict):
+                continue
+            content = msg.get('content')
+            if not isinstance(content, list):
+                continue
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                if block.get('type') != 'tool_use':
+                    continue
+                name = block.get('name', '')
+                inp = block.get('input') or {}
+                # Edit/Write/MultiEdit
+                if name in ('Edit', 'Write', 'MultiEdit'):
+                    fp = inp.get('file_path', '')
+                    # Strip leading project root prefix if present.
+                    if fp:
+                        path_touches[fp] = path_touches.get(fp, 0) + 1
+                # context7 MCP query
+                elif 'context7' in name:
+                    lib = inp.get('libraryName') or inp.get('library_name') or inp.get('libraryID')
+                    topic = inp.get('topic') or inp.get('query') or ''
+                    if lib:
+                        lib_queries.append({'library': str(lib), 'topic': str(topic)[:80]})
+except Exception as e:
+    sys.stderr.write(f'memory_stop: transcript walk failed: {e}\n')
+
+# Build candidates.
+ts = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%MZ')
+
+# Landmark candidates from touched source files.
+for fp, n in sorted(path_touches.items(), key=lambda kv: (-kv[1], kv[0])):
+    # Convert absolute path to repo-relative if it begins with the repo root.
+    rel = fp
+    cwd = os.environ.get('CLAUDE_PROJECT_DIR') or os.getcwd()
+    if fp.startswith(cwd + '/'):
+        rel = fp[len(cwd) + 1:]
+    if not is_source(rel):
+        continue
+    key = f'{rel} → landmarks.md'
+    if key in existing_keys:
+        continue
+    body = [
+        f'## CANDIDATE: {key}',
+        f'- Touched in this session: {n} time{"s" if n != 1 else ""}',
+        f'- Suggested role: <fill in from session context>',
+        f'- Source: file written/edited at {ts}',
+        '',
+    ]
+    candidates.append((key, 'landmarks', body))
+
+# Library candidates from context7 queries.
+seen_libs = set()
+for q in lib_queries:
+    lib = q['library']
+    if lib in seen_libs:
+        continue
+    seen_libs.add(lib)
+    key = f'{lib} → libraries.md'
+    if key in existing_keys:
+        continue
+    body = [
+        f'## CANDIDATE: {key}',
+        f'- Library: {lib}',
+        f'- Topics queried this session: {q["topic"] or "(no topic field)"}',
+        f'- Source: context7 MCP query at {ts}',
+        f'- Reminder: pin a version before promoting to canonical (lib@version is the stable key).',
+        '',
+    ]
+    candidates.append((key, 'libraries', body))
+
+# If nothing to add, exit cleanly.
+if not candidates:
+    sys.exit(0)
+
+# Append a session-tagged block to pending.
+prefix = f'\n\n<!-- session {ts} -->\n'
+new_block = prefix + '\n'.join('\n'.join(b) for _, _, b in candidates)
+with pending.open('a', encoding='utf-8') as f:
+    f.write(new_block)
+
+# Print a concise info note for the user.
+total_pending = len(re.findall(r'(?m)^##\s+CANDIDATE\b', existing)) + len(candidates)
+sys.stderr.write(
+    f'memory_stop: appended {len(candidates)} candidate(s) to .claude/memory/_pending.md '
+    f'(total pending: {total_pending}). Run /memory-flush to review.\n'
+)
+PY
+
+log_line memory_stop "ran end-of-turn extraction"
+
+# Refresh the continuity snapshot so even mid-session crashes / abrupt /clear
+# leave a usable _resume.md. Best-effort; never fail the hook.
+python3 "$CLAUDE_DOTDIR/hooks/lib/resume_writer.py" \
+  "$TRANSCRIPT" "$CLAUDE_PROJECT_ROOT" "stop" 2>>"$LOG_DIR/memory_stop.log" || true
+
+exit 0

package/obj/template/.claude/hooks/plantuml_syntax_guard.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# PlantUML Syntax Guard — PreToolUse(Write|Edit|MultiEdit)
+#
+# Validates every ```plantuml``` fenced block inside writes to docs/specs/*.md.
+# The spec template is diagram-driven; a spec with broken PlantUML is useless
+# to reviewers and breaks /spec-render. Catching it at the write boundary
+# prevents broken diagrams from ever landing on disk.
+#
+# How it validates:
+#   1. Extract every ```plantuml ...``` fenced block from the proposed content.
+#   2. For each block, pipe to `plantuml -checkonly -pipe` and capture exit code.
+#   3. Any non-zero exit → block the write with a reason naming the offending
+#      block (1-indexed) and its first line.
+#
+# Guide mode (advisory):
+#   - If `plantuml` is not on PATH, emit a one-line info message and allow.
+#   - If a spec has zero plantuml blocks, allow — spec_diagram_presence_guard
+#     is the hook that enforces presence.
+#
+# Template files (_TEMPLATE_*) are exempt.
+
+# shellcheck source=./lib/common.sh
+. "${BASH_SOURCE[0]%/*}/lib/common.sh"
+read_payload
+
+TOOL="$(payload_get .tool_name)"
+case "$TOOL" in
+  Write|Edit|MultiEdit) ;;
+  *) emit_allow ;;
+esac
+
+FILE="$(payload_get .tool_input.file_path)"
+[ -n "$FILE" ] || emit_allow
+rel="${FILE#$CLAUDE_PROJECT_ROOT/}"
+
+# Only enforce on spec artifacts.
+case "$rel" in
+  docs/specs/*.md) ;;
+  *) emit_allow ;;
+esac
+
+# Exempt templates.
+base="${rel##*/}"
+case "$base" in
+  _TEMPLATE_*|*TEMPLATE*.md) emit_allow ;;
+esac
+
+# Guide mode when plantuml is not installed. Emit once, then allow.
+if ! command -v plantuml >/dev/null 2>&1; then
+  emit_info "PlantUML Syntax Guard: \`plantuml\` CLI not found on PATH — running in guide mode. Install with 'brew install plantuml' (macOS) or 'apt-get install plantuml' (Debian/Ubuntu) to enable strict validation. Skipping syntax check for '$rel'."
+  log_line plantuml_syntax_guard "GUIDE (no plantuml) $rel"
+  emit_allow
+fi
+
+# Compute the post-write content (same merge strategy as artifact_template_guard).
+HOOK_FILE="$FILE" HOOK_TOOL="$TOOL" HOOK_REL="$rel" python3 <<'PY' >/tmp/.plantuml_guard_content.$$ 2>/dev/null
+import json, os, pathlib, sys
+
+payload = json.loads(os.environ.get("HOOK_PAYLOAD", "") or "{}")
+tool    = os.environ["HOOK_TOOL"]
+file_   = os.environ["HOOK_FILE"]
+ti      = payload.get("tool_input") or {}
+
+def current():
+    try:
+        return pathlib.Path(file_).read_text(encoding="utf-8")
+    except Exception:
+        return ""
+
+if tool == "Write":
+    content = ti.get("content") or ""
+elif tool == "Edit":
+    base = current()
+    old = ti.get("old_string") or ""
+    new = ti.get("new_string") or ""
+    if ti.get("replace_all"):
+        content = base.replace(old, new)
+    else:
+        content = base.replace(old, new, 1) if old in base else (base + new)
+elif tool == "MultiEdit":
+    content = current()
+    for edit in (ti.get("edits") or []):
+        old = edit.get("old_string") or ""
+        new = edit.get("new_string") or ""
+        if edit.get("replace_all"):
+            content = content.replace(old, new)
+        else:
+            content = content.replace(old, new, 1) if old in content else (content + new)
+else:
+    content = ""
+
+sys.stdout.write(content)
+PY
+
+CONTENT_FILE="/tmp/.plantuml_guard_content.$$"
+trap 'rm -f "$CONTENT_FILE"' EXIT
+
+# Extract plantuml blocks and validate each. Python does the heavy lifting so
+# we don't have to reason about multiline regex in bash.
+HOOK_REL="$rel" HOOK_CONTENT_FILE="$CONTENT_FILE" python3 <<'PY'
+import json, os, re, subprocess, sys
+
+rel   = os.environ["HOOK_REL"]
+try:
+    content = open(os.environ["HOOK_CONTENT_FILE"], encoding="utf-8").read()
+except Exception:
+    content = ""
+
+if not content.strip():
+    sys.exit(0)
+
+# Match ```plantuml ... ``` fenced blocks (case-insensitive language tag).
+fence_re = re.compile(r'^[ \t]*```[ \t]*plantuml[ \t]*$(.*?)^[ \t]*```[ \t]*$',
+                      re.DOTALL | re.IGNORECASE | re.MULTILINE)
+blocks = [m.group(1) for m in fence_re.finditer(content)]
+if not blocks:
+    # No PlantUML blocks → nothing to validate. Presence is a separate guard.
+    sys.exit(0)
+
+failures = []
+for idx, body in enumerate(blocks, start=1):
+    src = body.strip("\n")
+    # Ensure the block has a @startuml/@enduml envelope; plantuml requires it.
+    if "@startuml" not in src:
+        src = "@startuml\n" + src + "\n@enduml\n"
+    first_line = next((ln for ln in src.splitlines() if ln.strip() and not ln.strip().startswith("@start")), "").strip()[:80]
+    try:
+        r = subprocess.run(
+            ["plantuml", "-checkonly", "-pipe"],
+            input=src.encode("utf-8"),
+            capture_output=True,
+            timeout=15,
+        )
+    except FileNotFoundError:
+        # Race: vanished between the bash check and here. Guide mode.
+        sys.exit(0)
+    except subprocess.TimeoutExpired:
+        failures.append((idx, first_line, "plantuml -checkonly timed out after 15s"))
+        continue
+    if r.returncode != 0:
+        err = (r.stderr or r.stdout or b"").decode("utf-8", errors="replace").strip().splitlines()
+        detail = " | ".join(err[-3:]) if err else f"exit={r.returncode}"
+        failures.append((idx, first_line, detail))
+
+if not failures:
+    sys.exit(0)
+
+lines = [f"PlantUML Syntax Guard: '{rel}' has invalid PlantUML in {len(failures)} block(s). Fix and re-run."]
+for idx, first_line, detail in failures:
+    label = f'"{first_line}"' if first_line else "(empty first line)"
+    lines.append(f"  - block #{idx} {label}: {detail}")
+lines.append("Tip: render interactively via the plantuml MCP server, or run `/spec-lint <slug>` to iterate before saving.")
+
+print(json.dumps({
+    "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "deny",
+        "permissionDecisionReason": "\n".join(lines),
+    }
+}))
+PY