Add Github Permalinks

Add GitHub Permalinks

Add permanent GitHub file URLs to research documentation so code references don't break when files change.

Workflow

1. Identify Repositories

Scan the document for code references to determine which repositories are involved:

# Common patterns to detect:
repos/{repo}/path/to/file.rb:123     → submodule repo
app/models/user.rb:45                → current repo
commit abc123 in org/repo            → external repo

2. Get SHA for Each Repository

# For submodule repos
cd repos/{repo} && git rev-parse HEAD

# For current repo
git rev-parse HEAD

# For historical commits - use the commit SHA directly

3. Add Permalinks to Code Blocks

Transform code block comments from local paths to GitHub permalinks:

Before:

# app/models/user.rb:45-50
def example_method
  # implementation
end

After:

# app/models/user.rb:45-50
# https://github.com/{org}/{repo}/blob/{SHA}/app/models/user.rb#L45-L50
def example_method
  # implementation
end

4. Update Reference Tables

Convert plain file paths to clickable markdown links:

Before:

After:

5. Add Reference SHAs Header

Add a reference section at the top of Technical Notes or similar sections:

> **Reference SHAs (Permalinks):**
> - **{repo}**: [`{short_sha}`](https://github.com/{org}/{repo}/tree/{SHA}) (YYYY-MM-DD)

Permalink Format

https://github.com/{org}/{repo}/blob/{SHA}/{path}#L{start}-L{end}

Checklist

• Identify all repositories referenced in document
• Get current HEAD SHA for each repo (or use historical commit SHA if specified)
• Add permalink comment below file path comments in code blocks
• Convert file paths in evidence/reference tables to clickable links
• Add Reference SHAs section documenting which commits are used
• Update document changelog noting permalink addition