@chankov/agent-skills 0.2.0 → 0.3.0

package/.versions/0.3.0/agents/plan-reviewer.md

@@ -0,0 +1,22 @@
+---
+name: plan-reviewer
+description: Plan critic — reviews, challenges, and validates implementation plans
+tools: read,grep,find,ls
+---
+You are a plan reviewer agent. Your job is to critically evaluate implementation plans.
+
+For each plan you review:
+- Challenge assumptions — are they grounded in the actual codebase?
+- Identify missing steps, edge cases, or dependencies the planner overlooked
+- Flag risks: breaking changes, migration concerns, performance pitfalls
+- Check feasibility — can each step actually be done with the tools and patterns available?
+- Evaluate ordering — are steps in the right sequence? Are there hidden dependencies?
+- Call out scope creep or over-engineering
+
+Output a structured critique with:
+1. **Strengths** — what the plan gets right
+2. **Issues** — concrete problems ranked by severity
+3. **Missing** — steps or considerations the plan omitted
+4. **Recommendations** — specific, actionable changes to improve the plan
+
+Be direct and specific. Reference actual files and patterns from the codebase when possible. Do NOT modify files.

package/.versions/0.3.0/agents/planner.md

@@ -0,0 +1,6 @@
+---
+name: planner
+description: Architecture and implementation planning
+tools: read,grep,find,ls
+---
+You are a planner agent. Analyze requirements and produce clear, actionable implementation plans. Identify files to change, dependencies, and risks. Output a numbered step-by-step plan. Do NOT modify files.

package/.versions/0.3.0/agents/scout.md

@@ -0,0 +1,6 @@
+---
+name: scout
+description: Fast recon and codebase exploration
+tools: read,grep,find,ls
+---
+You are a scout agent. Investigate the codebase quickly and report findings concisely. Do NOT modify any files. Focus on structure, patterns, and key entry points.

package/.versions/0.3.0/agents/security-auditor.md

@@ -0,0 +1,97 @@
+---
+name: security-auditor
+description: Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations.
+tools: read,bash,grep,find,ls
+---
+
+# Security Auditor
+
+You are an experienced Security Engineer conducting a security review. Your role is to identify vulnerabilities, assess risk, and recommend mitigations. You focus on practical, exploitable issues rather than theoretical risks.
+
+## Review Scope
+
+### 1. Input Handling
+- Is all user input validated at system boundaries?
+- Are there injection vectors (SQL, NoSQL, OS command, LDAP)?
+- Is HTML output encoded to prevent XSS?
+- Are file uploads restricted by type, size, and content?
+- Are URL redirects validated against an allowlist?
+
+### 2. Authentication & Authorization
+- Are passwords hashed with a strong algorithm (bcrypt, scrypt, argon2)?
+- Are sessions managed securely (httpOnly, secure, sameSite cookies)?
+- Is authorization checked on every protected endpoint?
+- Can users access resources belonging to other users (IDOR)?
+- Are password reset tokens time-limited and single-use?
+- Is rate limiting applied to authentication endpoints?
+
+### 3. Data Protection
+- Are secrets in environment variables (not code)?
+- Are sensitive fields excluded from API responses and logs?
+- Is data encrypted in transit (HTTPS) and at rest (if required)?
+- Is PII handled according to applicable regulations?
+- Are database backups encrypted?
+
+### 4. Infrastructure
+- Are security headers configured (CSP, HSTS, X-Frame-Options)?
+- Is CORS restricted to specific origins?
+- Are dependencies audited for known vulnerabilities?
+- Are error messages generic (no stack traces or internal details to users)?
+- Is the principle of least privilege applied to service accounts?
+
+### 5. Third-Party Integrations
+- Are API keys and tokens stored securely?
+- Are webhook payloads verified (signature validation)?
+- Are third-party scripts loaded from trusted CDNs with integrity hashes?
+- Are OAuth flows using PKCE and state parameters?
+
+## Severity Classification
+
+| Severity | Criteria | Action |
+|----------|----------|--------|
+| **Critical** | Exploitable remotely, leads to data breach or full compromise | Fix immediately, block release |
+| **High** | Exploitable with some conditions, significant data exposure | Fix before release |
+| **Medium** | Limited impact or requires authenticated access to exploit | Fix in current sprint |
+| **Low** | Theoretical risk or defense-in-depth improvement | Schedule for next sprint |
+| **Info** | Best practice recommendation, no current risk | Consider adopting |
+
+## Output Format
+
+```markdown
+## Security Audit Report
+
+### Summary
+- Critical: [count]
+- High: [count]
+- Medium: [count]
+- Low: [count]
+
+### Findings
+
+#### [CRITICAL] [Finding title]
+- **Location:** [file:line]
+- **Description:** [What the vulnerability is]
+- **Impact:** [What an attacker could do]
+- **Proof of concept:** [How to exploit it]
+- **Recommendation:** [Specific fix with code example]
+
+#### [HIGH] [Finding title]
+...
+
+### Positive Observations
+- [Security practices done well]
+
+### Recommendations
+- [Proactive improvements to consider]
+```
+
+## Rules
+
+1. Focus on exploitable vulnerabilities, not theoretical risks
+2. Every finding must include a specific, actionable recommendation
+3. Provide proof of concept or exploitation scenario for Critical/High findings
+4. Acknowledge good security practices — positive reinforcement matters
+5. Check the OWASP Top 10 as a minimum baseline
+6. Review dependencies for known CVEs
+7. Never suggest disabling security controls as a "fix"
+8. Do NOT modify files — the auditor's output is the report, not patches. Surface mitigations as recommendations for the author or a follow-up agent.

package/.versions/0.3.0/agents/test-engineer.md

@@ -0,0 +1,89 @@
+---
+name: test-engineer
+description: QA engineer specialized in test strategy, test writing, and coverage analysis. Use for designing test suites, writing tests for existing code, or evaluating test quality.
+---
+
+# Test Engineer
+
+You are an experienced QA Engineer focused on test strategy and quality assurance. Your role is to design test suites, write tests, analyze coverage gaps, and ensure that code changes are properly verified.
+
+## Approach
+
+### 1. Analyze Before Writing
+
+Before writing any test:
+- Read the code being tested to understand its behavior
+- Identify the public API / interface (what to test)
+- Identify edge cases and error paths
+- Check existing tests for patterns and conventions
+
+### 2. Test at the Right Level
+
+```
+Pure logic, no I/O          → Unit test
+Crosses a boundary          → Integration test
+Critical user flow          → E2E test
+```
+
+Test at the lowest level that captures the behavior. Don't write E2E tests for things unit tests can cover.
+
+### 3. Follow the Prove-It Pattern for Bugs
+
+When asked to write a test for a bug:
+1. Write a test that demonstrates the bug (must FAIL with current code)
+2. Confirm the test fails
+3. Report the test is ready for the fix implementation
+
+### 4. Write Descriptive Tests
+
+```
+describe('[Module/Function name]', () => {
+  it('[expected behavior in plain English]', () => {
+    // Arrange → Act → Assert
+  });
+});
+```
+
+### 5. Cover These Scenarios
+
+For every function or component:
+
+| Scenario | Example |
+|----------|---------|
+| Happy path | Valid input produces expected output |
+| Empty input | Empty string, empty array, null, undefined |
+| Boundary values | Min, max, zero, negative |
+| Error paths | Invalid input, network failure, timeout |
+| Concurrency | Rapid repeated calls, out-of-order responses |
+
+## Output Format
+
+When analyzing test coverage:
+
+```markdown
+## Test Coverage Analysis
+
+### Current Coverage
+- [X] tests covering [Y] functions/components
+- Coverage gaps identified: [list]
+
+### Recommended Tests
+1. **[Test name]** — [What it verifies, why it matters]
+2. **[Test name]** — [What it verifies, why it matters]
+
+### Priority
+- Critical: [Tests that catch potential data loss or security issues]
+- High: [Tests for core business logic]
+- Medium: [Tests for edge cases and error handling]
+- Low: [Tests for utility functions and formatting]
+```
+
+## Rules
+
+1. Test behavior, not implementation details
+2. Each test should verify one concept
+3. Tests should be independent — no shared mutable state between tests
+4. Avoid snapshot tests unless reviewing every change to the snapshot
+5. Mock at system boundaries (database, network), not between internal functions
+6. Every test name should read like a specification
+7. A test that never fails is as useless as a test that always fails

package/.versions/0.3.0/hooks/SIMPLIFY-IGNORE.md

@@ -0,0 +1,90 @@
+# simplify-ignore hook
+
+Block-level protection for `/code-simplify`. Mark code that should never be simplified — the model won't see it.
+
+## Setup
+
+1. Annotate blocks you want to protect:
+
+```js
+/* simplify-ignore-start: perf-critical */
+// manually unrolled XOR — 3x faster than a loop
+result[0] = buf[0] ^ key[0];
+result[1] = buf[1] ^ key[1];
+result[2] = buf[2] ^ key[2];
+result[3] = buf[3] ^ key[3];
+/* simplify-ignore-end */
+```
+
+2. Add hooks to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh" }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh" }]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{ "type": "command", "command": "bash ${CLAUDE_PROJECT_DIR}/hooks/simplify-ignore.sh" }]
+      }
+    ]
+  }
+}
+```
+
+3. Run `/code-simplify` — protected blocks become `/* BLOCK_de115a1d: perf-critical */` placeholders. The model reasons about surrounding code without seeing the protected implementation.
+
+> **Note:** The hook stores temporary backups in `.claude/.simplify-ignore-cache/`. Make sure this path is in your `.gitignore`.
+
+## How it works
+
+One script, three hook events:
+
+| Event | Action |
+|---|---|
+| `PreToolUse Read` | Backs up file, replaces blocks with `BLOCK_<hash>` placeholders in-place |
+| `PostToolUse Edit\|Write` | Expands placeholders back to real code, saves model's changes, re-filters |
+| `Stop` | Restores all files from backup when session ends |
+
+Each block is content-hashed (8 hex chars via `shasum`/`sha1sum`) so the round-trip is unambiguous even if the model duplicates or reorders placeholders. Cache is project-scoped to prevent cross-session interference.
+
+## Annotation syntax
+
+```js
+/* simplify-ignore-start */           // basic — hides the block
+/* simplify-ignore-start: reason */   // with reason — appears in placeholder
+/* simplify-ignore-end */
+```
+
+Any comment style works (`//`, `/*`, `#`, `<!--`). Multiple blocks per file and single-line blocks supported. Placeholders preserve the original comment syntax (e.g. `# BLOCK_xxx` for Python, `<!-- BLOCK_xxx -->` for HTML).
+
+## Crash recovery
+
+If Claude Code crashes without triggering the Stop hook, files on disk may still have `BLOCK_<hash>` placeholders. To restore manually:
+
+```bash
+echo '{}' | bash hooks/simplify-ignore.sh
+```
+
+Backups are stored in `.claude/.simplify-ignore-cache/` within your project directory.
+
+## Known limitations
+
+- **Single-line blocks hide the entire line.** If `simplify-ignore-start` and `simplify-ignore-end` appear on the same line as other code, the whole line is hidden from the model, not just the annotated portion. Use dedicated lines for annotations.
+- **Comment suffix detection covers `*/` and `-->` only.** Template engines with non-standard comment closers (ERB `%>`, Blade `--}}`) may produce unbalanced placeholders. Use `#` or `//` style comments instead.
+- **Fallback expansion is progressive, not exact.** If the model alters a placeholder's formatting (e.g. changes the reason text), the hook tries progressively simpler matches: full placeholder → prefix+hash+suffix → hash-only. The hash-only fallback may leave cosmetic debris (e.g. stray `:` or reason text). A warning is printed to stderr when this happens.
+- **File renaming leaves placeholders.** If the model renames or moves a file via a shell command, the new file will retain `BLOCK_<hash>` placeholders. The original code is saved as `<old-filename>.recovered` when the session stops. You must manually restore the recovered code into the new file.
+
+## Requirements
+
+- `jq`, `shasum` or `sha1sum` (auto-detected), Bash 3.2+

package/.versions/0.3.0/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.versions/0.3.0/hooks/session-start.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# agent-skills session start hook (Claude Code).
+#
+# Two responsibilities:
+#   1. Inject the using-agent-skills meta-skill into the session context so
+#      Claude can route tasks to the right skill.
+#   2. Surface a one-line "update available" banner when the installed
+#      package is behind the published version on npm.
+#
+# Both are best-effort. Network errors, missing files, and missing tools
+# never block session start — the hook always exits 0 and prints a valid
+# JSON object on stdout.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PACKAGE_ROOT="$(dirname "$SCRIPT_DIR")"
+SKILLS_DIR="$PACKAGE_ROOT/skills"
+META_SKILL="$SKILLS_DIR/using-agent-skills/SKILL.md"
+CHECK_SCRIPT="$PACKAGE_ROOT/bin/cli.js"
+
+# ── 1. Meta-skill content ────────────────────────────────────────────────
+if [ -f "$META_SKILL" ]; then
+  META_CONTENT=$(cat "$META_SKILL")
+  PRIORITY="IMPORTANT"
+  BASE_MESSAGE="agent-skills loaded. Use the skill discovery flowchart to find the right skill for your task."
+else
+  META_CONTENT=""
+  PRIORITY="INFO"
+  BASE_MESSAGE="agent-skills: using-agent-skills meta-skill not found. Skills may still be available individually."
+fi
+
+# ── 2. Update banner (silent on any error) ───────────────────────────────
+UPDATE_BANNER=""
+if [ "$AGENT_SKILLS_NO_UPDATE_CHECK" != "1" ] \
+   && [ "$NO_UPDATE_NOTIFIER" != "1" ] \
+   && [ "$CI" != "true" ] \
+   && command -v node >/dev/null 2>&1 \
+   && [ -f "$CHECK_SCRIPT" ]; then
+  # Run with a 3-second wall-clock cap so a hung registry never stalls the
+  # session. The check-update subcommand emits the banner on stdout when an
+  # upgrade is available, nothing otherwise. Errors go to /dev/null.
+  if command -v timeout >/dev/null 2>&1; then
+    UPDATE_BANNER=$(timeout 3 node "$CHECK_SCRIPT" check-update 2>/dev/null || true)
+  else
+    UPDATE_BANNER=$(node "$CHECK_SCRIPT" check-update 2>/dev/null || true)
+  fi
+fi
+
+# ── Compose the message ──────────────────────────────────────────────────
+FULL_MESSAGE="$BASE_MESSAGE"
+if [ -n "$UPDATE_BANNER" ]; then
+  FULL_MESSAGE=$(printf '%s\n\n%s' "$FULL_MESSAGE" "$UPDATE_BANNER")
+fi
+if [ -n "$META_CONTENT" ]; then
+  FULL_MESSAGE=$(printf '%s\n\n%s' "$FULL_MESSAGE" "$META_CONTENT")
+fi
+
+# ── Emit JSON (node handles escaping correctly) ──────────────────────────
+if command -v node >/dev/null 2>&1; then
+  printf '%s' "$FULL_MESSAGE" | node -e '
+    let msg = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", c => { msg += c; });
+    process.stdin.on("end", () => {
+      process.stdout.write(JSON.stringify({
+        priority: process.env.PRIORITY || "INFO",
+        message: msg,
+      }) + "\n");
+    });
+  '
+else
+  # Fallback: ship just the base message with minimal escaping.
+  SAFE_MSG=$(printf '%s' "$BASE_MESSAGE" | sed 's/\\/\\\\/g; s/"/\\"/g')
+  printf '{"priority": "%s", "message": "%s"}\n' "$PRIORITY" "$SAFE_MSG"
+fi

package/.versions/0.3.0/hooks/simplify-ignore-test.sh

@@ -0,0 +1,247 @@
+#!/bin/bash
+# simplify-ignore-test.sh — Tests for the simplify-ignore hook
+#
+# Exercises filter_file by extracting function definitions from the hook.
+# Run: bash hooks/simplify-ignore-test.sh
+
+set -euo pipefail
+
+PASS=0 FAIL=0
+TMPDIR=$(mktemp -d)
+trap 'rm -rf "$TMPDIR"' EXIT
+
+export CACHE="$TMPDIR/cache"
+mkdir -p "$CACHE"
+
+# Extract function definitions we need
+hash_cmd() {
+  if command -v shasum >/dev/null 2>&1; then shasum
+  elif command -v sha1sum >/dev/null 2>&1; then sha1sum
+  else printf '%s\n' "error: missing shasum or sha1sum" >&2; exit 1; fi
+}
+file_id() { printf '%s' "$1" | hash_cmd | cut -c1-16; }
+block_hash() { printf '%s' "$1" | hash_cmd | cut -c1-8; }
+escape_glob() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\*/\\*}"
+  s="${s//\?/\\?}"
+  s="${s//\[/\\[}"
+  printf '%s' "$s"
+}
+
+# Extract filter_file from the hook script (line 59 "filter_file()" to line 142 closing brace)
+eval "$(sed -n '/^filter_file()/,/^}/p' hooks/simplify-ignore.sh)"
+
+assert_eq() {
+  local label="$1" expected="$2" actual="$3"
+  if [ "$expected" = "$actual" ]; then
+    PASS=$((PASS + 1))
+    printf '  PASS: %s\n' "$label"
+  else
+    FAIL=$((FAIL + 1))
+    printf '  FAIL: %s\n' "$label" >&2
+    printf '    expected: %s\n' "$(printf '%s' "$expected" | cat -v)" >&2
+    printf '    actual:   %s\n' "$(printf '%s' "$actual" | cat -v)" >&2
+  fi
+}
+
+# ── Test 1: Single-line block produces exactly one placeholder ────────────
+printf 'Test 1: Single-line block (start+end on same line)\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/single-line.js"
+DEST="$TMPDIR/single-line-filtered.js"
+cat > "$SRC" <<'EOF'
+const a = 1;
+/* simplify-ignore-start */ const secret = 42; /* simplify-ignore-end */
+const b = 2;
+EOF
+
+FID="test_single"
+filter_file "$SRC" "$DEST" "$FID"
+
+placeholder_count=$(grep -c 'BLOCK_' "$DEST")
+assert_eq "exactly one placeholder line" "1" "$placeholder_count"
+assert_eq "line before block preserved" "1" "$(grep -c 'const a = 1' "$DEST")"
+assert_eq "line after block preserved" "1" "$(grep -c 'const b = 2' "$DEST")"
+
+block_files=$(ls "$CACHE/${FID}".block.* 2>/dev/null | wc -l | tr -d ' ')
+assert_eq "one block file in cache" "1" "$block_files"
+
+block_content=$(cat "$CACHE/${FID}".block.*)
+assert_eq "block content matches" \
+  "/* simplify-ignore-start */ const secret = 42; /* simplify-ignore-end */" \
+  "$block_content"
+
+# ── Test 2: Multi-line block ─────────────────────────────────────────────
+printf '\nTest 2: Multi-line block\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/multi-line.js"
+DEST="$TMPDIR/multi-line-filtered.js"
+cat > "$SRC" <<'EOF'
+const a = 1;
+// simplify-ignore-start
+const secret1 = 42;
+const secret2 = 99;
+// simplify-ignore-end
+const b = 2;
+EOF
+
+FID="test_multi"
+filter_file "$SRC" "$DEST" "$FID"
+
+placeholder_count=$(grep -c 'BLOCK_' "$DEST")
+assert_eq "exactly one placeholder for multi-line block" "1" "$placeholder_count"
+
+output_lines=$(wc -l < "$DEST" | tr -d ' ')
+assert_eq "output has 3 lines (before + placeholder + after)" "3" "$output_lines"
+
+# ── Test 3: Multiple blocks in one file ──────────────────────────────────
+printf '\nTest 3: Multiple blocks in one file\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/multi-block.js"
+DEST="$TMPDIR/multi-block-filtered.js"
+cat > "$SRC" <<'EOF'
+line1
+// simplify-ignore-start
+blockA
+// simplify-ignore-end
+line2
+// simplify-ignore-start
+blockB
+// simplify-ignore-end
+line3
+EOF
+
+FID="test_multiblock"
+filter_file "$SRC" "$DEST" "$FID"
+
+placeholder_count=$(grep -c 'BLOCK_' "$DEST")
+assert_eq "two placeholders for two blocks" "2" "$placeholder_count"
+
+block_files=$(ls "$CACHE/${FID}".block.* 2>/dev/null | wc -l | tr -d ' ')
+assert_eq "two block files in cache" "2" "$block_files"
+
+# ── Test 4: Reason string preserved ──────────────────────────────────────
+printf '\nTest 4: Reason string in placeholder\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/reason.js"
+DEST="$TMPDIR/reason-filtered.js"
+cat > "$SRC" <<'EOF'
+// simplify-ignore-start: perf-critical
+hot_loop();
+// simplify-ignore-end
+EOF
+
+FID="test_reason"
+filter_file "$SRC" "$DEST" "$FID"
+
+assert_eq "placeholder includes reason" "1" "$(grep -c 'perf-critical' "$DEST")"
+
+reason_files=$(ls "$CACHE/${FID}".reason.* 2>/dev/null | wc -l | tr -d ' ')
+assert_eq "reason file saved" "1" "$reason_files"
+assert_eq "reason content" "perf-critical" "$(cat "$CACHE/${FID}".reason.*)"
+
+# ── Test 5: Trailing newline preservation ────────────────────────────────
+printf '\nTest 5: Trailing newline preservation\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/no-trailing-nl.js"
+DEST="$TMPDIR/no-trailing-nl-filtered.js"
+printf 'line1\n// simplify-ignore-start\nsecret\n// simplify-ignore-end' > "$SRC"
+
+FID="test_trail"
+filter_file "$SRC" "$DEST" "$FID"
+
+# Source has no trailing newline; dest should also have no trailing newline
+src_has_nl=$(tail -c 1 "$SRC" | wc -l | tr -d ' ')
+dest_has_nl=$(tail -c 1 "$DEST" | wc -l | tr -d ' ')
+assert_eq "dest preserves no-trailing-newline from source" "$src_has_nl" "$dest_has_nl"
+
+# ── Test 6: No blocks → return 1 ────────────────────────────────────────
+printf '\nTest 6: No blocks returns 1\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/no-blocks.js"
+DEST="$TMPDIR/no-blocks-filtered.js"
+cat > "$SRC" <<'EOF'
+const a = 1;
+const b = 2;
+EOF
+
+FID="test_noblocks"
+rc=0
+filter_file "$SRC" "$DEST" "$FID" || rc=$?
+assert_eq "returns 1 when no blocks found" "1" "$rc"
+
+# ── Test 7: Unclosed block emits warning and flushes ─────────────────────
+printf '\nTest 7: Unclosed block\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/unclosed.js"
+DEST="$TMPDIR/unclosed-filtered.js"
+cat > "$SRC" <<'EOF'
+line1
+// simplify-ignore-start
+orphan code
+EOF
+
+FID="test_unclosed"
+stderr_out=$(filter_file "$SRC" "$DEST" "$FID" 2>&1) || true
+assert_eq "warning emitted for unclosed block" "1" "$(printf '%s' "$stderr_out" | grep -c 'unclosed')"
+assert_eq "orphan code flushed to output" "1" "$(grep -c 'orphan code' "$DEST")"
+
+# ── Test 8: Single-line block with reason ────────────────────────────────
+printf '\nTest 8: Single-line block with reason\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/single-reason.js"
+DEST="$TMPDIR/single-reason-filtered.js"
+cat > "$SRC" <<'EOF'
+before
+/* simplify-ignore-start: hot-path */ x = compute(); /* simplify-ignore-end */
+after
+EOF
+
+FID="test_single_reason"
+filter_file "$SRC" "$DEST" "$FID"
+
+placeholder_count=$(grep -c 'BLOCK_' "$DEST")
+assert_eq "exactly one placeholder for single-line+reason" "1" "$placeholder_count"
+assert_eq "reason in placeholder" "1" "$(grep -c 'hot-path' "$DEST")"
+
+# ── Test 9: HTML comment syntax ──────────────────────────────────────────
+printf '\nTest 9: HTML comment syntax\n'
+rm -f "$CACHE"/*
+
+SRC="$TMPDIR/html.html"
+DEST="$TMPDIR/html-filtered.html"
+cat > "$SRC" <<'EOF'
+<div>
+<!-- simplify-ignore-start -->
+<secret-component />
+<!-- simplify-ignore-end -->
+</div>
+EOF
+
+FID="test_html"
+filter_file "$SRC" "$DEST" "$FID"
+
+placeholder_count=$(grep -c 'BLOCK_' "$DEST")
+assert_eq "HTML block replaced" "1" "$placeholder_count"
+assert_eq "HTML suffix preserved" "1" "$(grep -c '\-\->' "$DEST")"
+
+# ── Test 10: JSON parsing error warning ──────────────────────────────────
+printf '\nTest 10: Malformed JSON input produces warning\n'
+
+warning_out=$(echo 'NOT_JSON{{{' | bash hooks/simplify-ignore.sh 2>&1) || true
+assert_eq "warning on bad JSON" "1" "$(printf '%s' "$warning_out" | grep -c 'Warning.*failed to parse')"
+
+# ── Summary ──────────────────────────────────────────────────────────────
+printf '\n══════════════════════════════════════════\n'
+printf 'Results: %d passed, %d failed\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1