feat: Local patch tracking and update-safe SYSTEM file management

[jlacour-git]

Summary

PAI's SYSTEM/USER two-tier architecture (documented in SYSTEM/SYSTEM_USER_EXTENDABILITY.md) protects USER-tier customizations during updates. However, it doesn't address a common real-world scenario: users who fix bugs in SYSTEM-tier files before those fixes are merged upstream.

When a user patches a SYSTEM file locally (e.g., fixing a bug in UpdateCounts.ts or statusline-command.sh), that fix gets silently overwritten on the next PAI update. There's no mechanism to detect, warn about, or preserve these local modifications.

Real-World Examples

Example 1: UpdateCounts.ts (see #642)
A user fixes the missing work/research/ratings counters. The fix lives in hooks/handlers/UpdateCounts.ts — a SYSTEM file. Next PAI release overwrites it with the old broken version.

Example 2: Generated files with cached identity
SKILL.md is generated by CreateDynamicCore.ts and caches {DAIDENTITY.NAME} at build time. After a PAI update that ships a new SKILL.md, the user's identity reverts to the default "PAI" instead of their configured name. There's no auto-rebuild trigger.

Proposed Solution

Three lightweight mechanisms that extend the existing SYSTEM/USER architecture:

1. LOCAL_PATCHES.md Convention

A standardized file at ~/.claude/LOCAL_PATCHES.md where users (or their DA) track local modifications to SYSTEM files:

# Local Patches to PAI SYSTEM Files
## Active Patches
### UpdateCounts.ts - Missing counters
**File:** hooks/handlers/UpdateCounts.ts
**Issue:** #642
**PR:** _pending_

• Checked by the DA before modifying SYSTEM files
• Serves as a pre/post-update checklist
• Could be read by an install/update script to warn about conflicts

2. PAIUpgrade Conflict Check

Add a step to the PAIUpgrade Upgrade workflow (between scoring and output) that:

1. Reads LOCAL_PATCHES.md if it exists
2. Cross-references recommended techniques against locally-patched files
3. Flags conflicts in the upgrade report with a ⚠️ LOCAL PATCH CONFLICT warning

This makes the upgrade workflow aware of local state, which is consistent with Thread 1's existing PAI State analysis.

3. Stale Generated File Detection

For generated files like SKILL.md, a lightweight check (in SessionStart or the install process) that compares settings.json mtime against SKILL.md mtime. If settings is newer, auto-rebuild:

if [ "$SETTINGS_FILE" -nt "$SKILL_MD" ]; then
  bun ~/.claude/skills/PAI/Tools/CreateDynamicCore.ts
fi

This prevents the class of bug where identity/config changes don't propagate to generated files.

How This Fits the Architecture

• Extends the SYSTEM/USER pattern, doesn't replace it
• USER files remain protected by the existing architecture
• SYSTEM file patches get a tracking mechanism until they're upstreamed
• Generated files get a staleness check
• PAIUpgrade becomes aware of local state (consistent with its user-context-first design)

Scope

This is a feature proposal, not a PR. Happy to contribute implementation if the approach is approved.

Related: #642 (the bug that surfaced this gap)

[jlacour-git]

Concrete Implementation for Mechanism 3 (Stale Generated File Detection)

Following up with a local implementation I've applied for the settings.json → SKILL.md staleness detection proposed in the issue.

The Gap

LoadContext.hook.ts already rebuilds SKILL.md when Component .md files are newer — but it doesn't check settings.json. Since CreateDynamicCore.ts resolves template variables ({DAIDENTITY.NAME}, {PRINCIPAL.NAME}, etc.) from settings.json, changing identity config leaves SKILL.md stale.

This was the root cause of the identity bug where voice lines said "PAI" after renaming to "zora" — components hadn't changed, so no rebuild fired.

The Fix (4 lines, after the existing checkDir() call)

// In LoadContext.hook.ts, after: needsRebuild = checkDir(componentsDir);

// Also rebuild if settings.json is newer (template variables may have changed)
if (!needsRebuild) {
  try {
    const settingsPath = join(paiDir, 'settings.json');
    const settingsStat = require('fs').statSync(settingsPath);
    if (settingsStat.mtimeMs > skillMdStat!.mtimeMs) {
      needsRebuild = true;
    }
  } catch {}
}

Why This Works

Trigger	Before	After
Component .md edited	✅ Rebuild	✅ Rebuild
Algorithm version changed	✅ Rebuild	✅ Rebuild
SKILL.md missing	✅ Rebuild	✅ Rebuild
settings.json changed (name, voice, timezone)	❌ No rebuild	✅ Rebuild

Performance

• One extra statSync() (~0.1ms), only runs when components haven't changed
• CreateDynamicCore.ts takes ~23ms when triggered
• Net startup impact: negligible

This addresses the "Stale Generated File Detection" mechanism from the original proposal. Applied locally and tracked in LOCAL_PATCHES.md. Happy to submit as a PR if useful.

[kaimagnus]

Partial fix landed in commit 72bf79b: LoadContext.hook.ts now checks settings.json mtime against SKILL.md and triggers a rebuild when settings change. This addresses the specific scenario where identity changes (name, voice) in settings.json left SKILL.md stale.

The broader patch-tracking feature proposed in this issue is still open for discussion.

[jlacour-git]

Update: Patch tracking workflow validated in practice

Just completed a sync from the latest repo and the LOCAL_PATCHES.md reconciliation procedure worked well:

• 4 active patches were tracked (Relative Paths and Preresequites #3 settings.json mtime, Load Dynamic Requirements runs repeatedly? #4 VoiceGate non-Kitty, There are a number of hooks referenced in .claude/settings.json but not included in the hooks folder #5 TELOS injection, fix: replace hardcoded user paths with tilde notation in Claude settings #6 SystemFileGuard)
• Reconciliation correctly identified that patch Relative Paths and Preresequites #3 is now upstream (via commit 72bf79b, as @kaimagnus confirmed above) and patch Load Dynamic Requirements runs repeatedly? #4 was superseded by the improved TERM_PROGRAM detection from PR fix(hooks): enforce socket-based Kitty remote control in v3.0 tab-setter #675
• Patches There are a number of hooks referenced in .claude/settings.json but not included in the hooks folder #5 and fix: replace hardcoded user paths with tilde notation in Claude settings #6 remain active locally, pending review of PR feat(hooks): deterministic TELOS injection + SystemFileGuard #727
• No local modifications were accidentally lost during the file-level diff step

The SystemFileGuard.hook.ts (proposed in #727) also worked during the session — it flagged when edits targeted locally-patched SYSTEM files.

The broader patch-tracking mechanism (LOCAL_PATCHES.md + reconciliation procedure + SystemFileGuard hook) is a lightweight but effective solution for the gap described in this issue. Happy to contribute further if there's interest in formalizing this upstream.

[nbost130]

Real-world approach: Version-bump + USER steering rules

We ran into this exact scenario and arrived at a practical solution that works without additional tooling:

The Problem We Hit

We added three improvements to Algorithm v1.8.0 (deploy verification, output templates, batch file edits). These were discovered through PAI's own reflection mining pipeline. But edits to Components/Algorithm/v1.8.0.md get overwritten when upstream updates land a new version.

Our Solution (two layers)

Layer 1 — Version bump (inline, optimal placement):

• Copy v1.8.0.md → v1.8.1.md with our additions
• Update LATEST → v1.8.1
• When upstream releases v1.9.0, git diff v1.8.0.md v1.8.1.md shows exactly our additions
• Merge our additions into v1.9.0 (or drop if upstream added the same thing)
• The diff IS the patch tracker

Layer 2 — USER steering rules (permanent backup):

• Same improvements written as steering rules in USER/AISTEERINGRULES.md
• Survives any upstream update unconditionally
• Uses Statement/Bad/Correct format for behavioral enforcement
• Acts as safety net if we forget to re-apply during merge

Why This Works

• Git IS the patch tracker — no additional tooling needed
• Two-layer redundancy — inline (optimal) + steering rules (permanent)
• Merge is explicit — diff shows exactly what we added, easy to re-apply or discard
• No new infrastructure — just versioning discipline + the existing USER tier

The LOCAL_PATCHES.md approach from @jlacour-git is more systematic for users with many patches. For users with a few Algorithm improvements, version-bumping keeps it simple.

[danielmiessler]

Hey @jlacour-git, thanks for raising this, and sorry it sat for a while.

We're changing how LifeOS ships. Instead of cloning a full ~/.claude directory and running it as a complete system, LifeOS is becoming a skill you install through an agentic installer. The installer hands integration to your own AI, which reads your actual machine (your OS, your paths, your harness) and wires the hooks and system prompt in where they belong.

That's aimed right at what you hit here. The old "one directory, one layout, hope it matches your setup" approach is exactly what broke for so many people, and the new model should handle it far better because your AI does the integration per machine instead of us guessing.

So we're closing this in prep for that release. If it still bites you once the skill-based version is out, reopen or file a fresh one and we'll jump on it. Appreciate you taking the time.