Interim Solution: Local Patch Tracking + Upstream Monitoring

[jlacour-git]

Interim Solution: Local Patch Tracking + Upstream Monitoring

Following up on the contribution pipeline discussion in #909. While Daniel and @ksylvan work on the staging repo and formal process, here's a system I've been using to manage local fixes between releases.

The Problem

Every PAI user who fixes bugs locally faces the same cycle:

1. Fix something locally
2. New release drops
3. Which fixes did upstream include? Which patches do I re-apply? Did they change the same files?

Multiply that by 20+ patches across 3 version upgrades and it gets messy fast.

What This Is

Three tools that work together:

1. LOCAL_PATCHES.md — A structured registry for every local modification to SYSTEM files. Each patch has: files modified, linked issue/PR, problem description, and fix description. Patches are tracked as ACTIVE or RETIRED with clear lifecycle rules.

2. UpgradeCheck.ts — Run before upgrading. It parses your LOCAL_PATCHES.md, diffs each patched file against the target release, checks linked GitHub issues, and classifies every patch as SAFE (carries forward), CONFLICT (merge needed), or RETIRE (upstream fixed it). Turns a scary upgrade into a checklist.

bun PAI/Tools/UpgradeCheck.ts v4.0.3

=== PAI Upgrade Check: v4.0.2 -> v4.0.3 ===
Active patches: 18
Classification: 2 CONFLICT, 3 RETIRE, 1 CHECK, 12 SAFE

3. UpstreamScan.ts — Monitors the repo for new issues, PRs, and discussions. Uses a digest file (JSON) that tracks what you've seen and what you decided about each item. Disposition-based filtering means you only see new stuff or items with new activity. Detects when you've participated in a thread.

bun PAI/Tools/UpstreamScan.ts

The scan outputs structured JSON that your assistant then deep-dives — fetching comments, reading PR diffs, cross-referencing against your local patches.

How I Use It

"Check upstream" triggers a scan. The assistant runs UpstreamScan.ts, gets the JSON, then does the analysis work: classifying new items, checking for overlap with my patches, fetching relevant comments, and producing a report with concrete actions per item.

Before upgrading to a new version, I run UpgradeCheck.ts. It tells me exactly which patches need attention and which carry forward cleanly. Has worked well across 4.0.0 through 4.0.3.

Files

All files are in this gist: https://gist.github.com/jlacour-git/0e2ab62014dc5bcc3977be82ba26e68a

File	What It Does
LOCAL_PATCHES-TEMPLATE.md	Template with structure, reconciliation procedure, example entries
UpstreamScan.ts	Repo monitor with disposition tracking and participation detection
UpgradeCheck.ts	Pre-upgrade patch analysis (SAFE/CONFLICT/RETIRE classification)
UPSTREAM-DIGEST-TEMPLATE.json	Empty digest with schema documentation
ScanWorkflow.md	The full workflow the assistant follows during a scan

Setup

1. Copy LOCAL_PATCHES-TEMPLATE.md to ~/.claude/LOCAL_PATCHES.md
2. Copy UPSTREAM-DIGEST-TEMPLATE.json to wherever you want (the tools default to ~/.claude/skills/_UPSTREAMWATCH/)
3. Put UpstreamScan.ts and UpgradeCheck.ts in ~/.claude/PAI/Tools/
4. Clone the PAI repo somewhere (~/PAI/) — UpgradeCheck needs it for git diffs
5. Start documenting your patches in LOCAL_PATCHES.md

The scan workflow is meant to be read by your assistant. You can put it in a skill, or just reference it manually.

Limitations

• UpgradeCheck.ts assumes the repo has tagged releases in the Releases/vX.Y/.claude/ directory structure that PAI uses.
• This is an interim setup. Once the formal contribution pipeline is in place, some of this becomes unnecessary.

Happy to answer questions or help adapt it to your setup!

[jarednwilson]

Oh my gosh, you are such a genius. This is so needed. Thank you for posting; I really appreciate you.

Because of the problem you have just solved, I basically just stopped with any upgrades because it's just too painful. Ill go from a patched working system, and then I upgrade and basically spend hours and hours and hours trying to get the new "non patched" system to work. This is an elegant solution to that problem. I really wish I had started with it from the get-go because I truly have no idea what all I've patched.

[jlacour-git]

Thank you for your kind words (although I definitely would leave the genius praise to others, e.g. Daniel who designed and implemented a fantastic concept!). Glad it helps.

Regarding "I truly have no idea what all I've patched": try to ask your PAI to carefully analyse the code, identify changes and create a foundation. That should be possible. Maybe not perfect, but much better than nothing.

[virtualian]

@jlacour-git Thanks from me too; I've just implemented your mods.

[DolphusCY]

@jlacour-git Thanks for this J. Very cool stuff

[AojdevStudio]

gonna try it today. Not waiting to get slammed with a 5hr needle in a haystack install of the next release

[jlacour-git]

Thanks, glad to hear it's working for you both!

If you hit any rough edges during setup or on your next upgrade, just ping me here. The tracking system is pretty battle-tested at this point — been through two major PAI version upgrades without losing any local modifications.

[jlacour-git]

Update: Fix for Missed Discussion Comments

Found a bug in 05-ScanWorkflow.md where the manual comment deep-dive step was missing nested replies.

The Problem

GitHub Discussions have threaded replies — comments can have sub-comments. The UpstreamScan.ts tool correctly fetches and counts these (it queries replies(first: 10) on each comment node). But the workflow's Step 3 only had a REST API example for issues, not discussions. When the LLM needed to deep-dive discussion comments in Step 5, it improvised a simpler GraphQL query without replies and missed nested threads.

Example: a discussion shows 5 comments in the scan report, but manual fetching only returns 2 (the top-level ones). The other 3 are replies to those comments.

The Fix

Added a discussion-specific GraphQL template to Step 3 that includes replies:

discussion(number: NNN) {
  comments(first: 20) {
    totalCount
    nodes {
      author { login } body createdAt
      replies(first: 10) {
        totalCount
        nodes { author { login } body createdAt }
      }
    }
  }
}

Plus a warning: "Always include replies in discussion queries."

Gist updated — 05-ScanWorkflow.md now has the fix.