@gurupanguji

Bare URL Markdown Binding Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Catch stray bare blog URLs in markdown post bodies before they land in the repo, and require those URLs to be wrapped in markdown link syntax.

Architecture: Extend the existing post validator so the rule runs in the same places the repo already enforces post policy: local pre-commit, local pre-push, and CI. Keep the first version narrow by checking for bare gurupanguji.com blog URLs in _posts/*.md bodies only.

Tech Stack: Python 3, repo-managed git hooks, markdown content, unittest

---

Task 1: Extend Post Validation With A Bare URL Rule

Files:

• Modify: scripts/validate_posts.py

• Step 1: Add a body-level URL scanning helper

Read post body text after front matter and scan line by line for bare blog URLs.

• Step 2: Keep the first version narrow

Flag only https://gurupanguji.com/blog/... URLs that appear as plain text in post bodies.

• Step 3: Exclude valid markdown and embed contexts

Skip URLs that appear:

• inside existing markdown links [label](url)
• inside angle-bracket autolinks <https://...> if allowed
• inside inline code
• inside fenced code blocks

• inside raw HTML attributes such as iframe src

• Step 4: Emit actionable errors

Return errors with file path, line number, and the offending bare URL so authors can fix the exact line quickly.

Task 2: Add Coverage For The New Rule

Files:

• Modify: tests/test_validate_posts.py

• Step 1: Add a passing case for markdown-wrapped URLs

Verify the validator accepts [url](url) in post body text.

• Step 2: Add a failing case for bare blog URLs

Verify the validator rejects plain https://gurupanguji.com/blog/... in post body text.

• Step 3: Add ignore-context cases

Verify the validator does not flag matching URLs inside inline code, fenced code blocks, or HTML embed attributes.

• Step 4: Keep current snippet validation tests intact

Do not regress the existing scheduled-post and snippet alignment checks.

Task 3: Verify Hook And CI Behavior Through The Shared Validator

Files:

• Verify: hooks/pre-commit
• Verify: hooks/pre-push

• Verify: .github/workflows/validate_posts.yml

• Step 1: Confirm local hooks already flow through the validator

Inspect the hook scripts and ensure no extra hook-specific logic is needed for this rule.

• Step 2: Confirm CI inherits the rule automatically

Because CI already runs scripts/validate_posts.py, no new workflow file should be required.

Task 4: Run Focused Verification

Files:

• Verify: scripts/validate_posts.py

• Verify: tests/test_validate_posts.py

• Step 1: Run unit tests

Run: python3 -m unittest tests/test_validate_posts.py Expected: all validator tests pass

• Step 2: Run the validator

Run: python3 scripts/validate_posts.py --today "$(date +%F)" Expected: Validated ... post(s) successfully.

• Step 3: Review diff

Run: git diff --stat Expected: validator, tests, and docs only

Task 5: Land The Documentation And Implementation Together

Files:

• Modify: scripts/validate_posts.py
• Modify: tests/test_validate_posts.py
• Add: docs/superpowers/plans/2026-03-24-bare-url-markdown-binding-implementation-plan.md

• Add: docs/superpowers/specs/2026-03-24-bare-url-markdown-binding-design.md

• Step 1: Commit the change set

git add scripts/validate_posts.py tests/test_validate_posts.py docs/superpowers/plans/2026-03-24-bare-url-markdown-binding-implementation-plan.md docs/superpowers/specs/2026-03-24-bare-url-markdown-binding-design.md
git commit -m "feat: validate bare blog URLs in markdown posts"