@gurupanguji

Source Citation Rendering 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: Replace the risky raw markdown blockquote plus Source: pattern with a markdown-only standalone source-link shape across the safe archive set, then block the old pattern from being added again.

Architecture: Add one narrow normalizer that rewrites only the safe markdown quote-source shape into the canonical [Source: ...](...) form, and also repairs any temporary gp-quote HTML introduced during remediation. Extend the post validator so future content cannot rely on Kramdown’s accidental citation folding or drift back to HTML quote markup.

Tech Stack: Python 3, unittest, regex/string parsing, Jekyll markdown content, existing repository validators

Task 1: Add Failing Tests For Safe Source-Citation Conversion

Files:

Create: tests/test_normalize_source_citations.py
Create: scripts/normalize_source_citations.py
Step 1: Add a single-paragraph quote conversion test

Assert that:

> Quoted text.

Source: [Example Story](https://example.com/story)

becomes:

> Quoted text.

[Source: Example Story](https://example.com/story)

Step 2: Add a multi-paragraph quote conversion test

Assert that multiple markdown quote paragraphs remain blockquote paragraphs and the source becomes the standalone markdown link line.

Step 3: Run the test file to verify it fails

Run: python3 -m unittest tests/test_normalize_source_citations.py Expected: FAIL because the normalizer does not exist yet

Task 2: Implement The Minimal Safe Source-Citation Normalizer

Files:

Create: scripts/normalize_source_citations.py
Test: tests/test_normalize_source_citations.py
Step 1: Add helpers to split front matter from body

Keep YAML front matter unchanged and operate only on the markdown body.

Step 2: Add a narrow matcher for the risky pattern

Match only:

one contiguous markdown blockquote run
blank line
one Source: [title](url) line
Step 3: Render the markdown-safe canonical source link

Output:

original blockquote lines preserved
blank line after the quote
[Source: Title](url) as the canonical source line
Step 4: Run the focused test file

Run: python3 -m unittest tests/test_normalize_source_citations.py Expected: PASS for the safe conversion cases

Task 3: Add Failing Tests For Skip Cases And CLI Behavior

Files:

Modify: tests/test_normalize_source_citations.py
Modify: scripts/normalize_source_citations.py
Step 1: Add a malformed source-line skip test

Use a quote followed by Source: text that is not a valid markdown link and assert the file is skipped.

Step 2: Add a multiple-source-lines skip test

Use one quote block with two adjacent Source: lines and assert the normalizer skips it as ambiguous.

Step 3: Add a gp-quote rollback test

Use a temporary gp-quote HTML block and assert the normalizer converts it back into the markdown-only canonical shape.

Step 4: Add dry-run versus --write tests

Assert that default execution reports pending rewrites without modifying files, and --write updates safe files in place.

Step 5: Run the test file to verify the new cases fail first

Run: python3 -m unittest tests/test_normalize_source_citations.py Expected: FAIL until skip logic and CLI behavior are implemented

Task 4: Implement Skip Reporting And CLI

Files:

Modify: scripts/normalize_source_citations.py
Test: tests/test_normalize_source_citations.py
Step 1: Add a result model for converted and skipped files

Track:

status
changed flag
rewritten text
skip reasons
Step 2: Add dry-run default and --write mode

Default to reporting only. Require --write to edit files.

Step 3: Add optional path targeting

Support one or more explicit post paths so individual files can be tested before a full run.

Step 4: Run the full source-citation normalizer test file

Run: python3 -m unittest tests/test_normalize_source_citations.py Expected: PASS

Task 5: Add The Validator Guardrail

Files:

Modify: scripts/validate_posts.py
Modify: tests/test_validate_posts.py
Step 1: Add failing validator tests for the risky raw markdown pattern

Cover:

a post that uses raw markdown blockquote plus Source: and should fail
a post that uses the markdown-safe source link shape and should pass
a post that uses temporary gp-quote HTML and should fail
Step 2: Add a narrow detection helper

Flag only the precise unsafe shape that triggers accidental Kramdown cite generation.

Step 3: Gate enforcement behind a policy start date

Apply the guardrail only to posts on or after the new policy date so the historical archive can be cleaned in a controlled pass.

Step 4: Run validator tests

Run: python3 -m unittest tests/test_validate_posts.py Expected: PASS

Task 6: Audit The Real Candidate Set Before Writing

Files:

Verify: _posts/*.md
Verify: scripts/normalize_source_citations.py
Step 1: Run the new normalizer in dry-run mode across the repo

Run: python3 scripts/normalize_source_citations.py Expected:

summary of safe candidates
summary of skipped files
no files modified
Step 2: Spot-check the candidate set

Open:

the two issue posts
at least one older archive post
at least one post with commentary after the quote
Step 3: Confirm the candidate list is narrow enough

If the script is matching noisy shapes, tighten the matcher before writing changes.

Task 7: Apply The Bulk Archive Cleanup

Files:

Modify: affected posts in _posts/
Verify: scripts/normalize_source_citations.py
Step 1: Run the script with --write

Run: python3 scripts/normalize_source_citations.py --write Expected:

only safe candidates are rewritten
skipped files remain untouched
a clear summary of converted and skipped files is printed
Step 2: Review the batch diff

Run: git diff --stat Expected: spec, plan, new script/tests, validator/layout changes, and the converted posts

Step 3: Manually inspect representative converted posts

Check that:

quote text is preserved
citation remains inside the quote intentionally
surrounding prose did not drift

Task 8: Verify Repository Compatibility

Files:

Verify: tests/test_normalize_source_citations.py
Verify: tests/test_validate_posts.py
Verify: scripts/validate_posts.py
Step 1: Run unit tests

Run:

python3 -m unittest \
  tests/test_normalize_source_citations.py \
  tests/test_validate_posts.py

Expected: PASS

Step 2: Run the post validator

Run: python3 scripts/validate_posts.py --today 2026-03-27 Expected: PASS

Step 3: Spot-check rewritten source from the affected posts

Inspect the two issue posts plus one older converted sample and confirm the canonical markdown shape is present.

Task 9: Commit, Push, And Open The PR

Files:

Modify: all tracked files touched by this work
Step 1: Review git status and git diff --stat

Confirm only intended files changed.

Step 2: Commit the branch

Run:

git add docs/superpowers/specs/2026-03-27-source-citation-rendering-design.md \
        docs/superpowers/plans/2026-03-27-source-citation-rendering-implementation-plan.md \
        scripts/normalize_source_citations.py \
        scripts/validate_posts.py \
        tests/test_normalize_source_citations.py \
        tests/test_validate_posts.py \
        _layouts/post.html \
        _posts
git commit -m "fix: normalize source citations in quoted link posts"

Step 3: Push and open the PR

Run:

git push -u origin fix/source-citation-rendering
gh pr create --fill

Expected: branch is pushed and PR is open for review