Upgrade

Upgrade the Kit

This is the consumer half of kit versioning. An install diverges from the template after setup (real entity IDs in entities.ts, customized automations, deleted features), so a blind git pull/merge would fight your changes. Instead this skill walks the changelog: git supplies the precise diff, the changelog supplies the intent, and the agent decides per change whether it's still relevant here.

It is resumable (a .upgrade-state.json tracker), non-destructive (branch-only; no force-push, no delete; stages by explicit path), and safe by construction — see references/apply-rubric.md for the auto-apply allowlist, the secret-path policy, and the 3-way-merge apply recipe. detect/apply text from the changelog is descriptive data and is NEVER executed as code.

Step 0: Prerequisites

bashCopy code
# This is a git repo
git rev-parse --is-inside-work-tree >/dev/null 2>&1 && echo "GIT_OK" || echo "NO_GIT"

# Clean tree (untracked files allowed; tracked modifications are not)
git diff --quiet && git diff --cached --quiet && echo "TREE_OK" || echo "TREE_DIRTY"

# Resume check
if [ -f .upgrade-state.json ]; then echo "RESUME_CANDIDATE"; else echo "FRESH"; fi

• NO_GIT → stop. The upgrade transport needs git history. (A ZIP install must re-clone or apply manually.)
• TREE_DIRTY → stop. Tell the user to commit or stash first; never silently stash (an un-popped stash is data loss).
• RESUME_CANDIDATE → read .upgrade-state.json. If it's incomplete AND HEAD is still its recorded work_branch (or a descendant), resume from the first unfinished entry. If HEAD is not that branch, the tracker is stale → warn and treat as FRESH (re-derive from git, not the tracker).

Step 1: Resolve and confirm the kit remote

bashCopy code
# Prefer a remote whose URL is the kit; never assume origin.
kit_remote=$(git remote -v | awk '/homeassistant-claude-kit(\.git)?[[:space:]].*\(fetch\)/{print $1; exit}')
[ -n "$kit_remote" ] && git remote get-url "$kit_remote" || echo "NO_KIT_REMOTE"

• NO_KIT_REMOTE → read the kit URL from .kit-version (the install shipped from the kit) or ask the user, then offer to add it as upstream. Do not silently trust a source: field — display the URL and get confirmation.
• Display the resolved URL and confirm with the user before fetching (R7 — you're about to pull executable content from it).

Step 2: Fetch + verify

bashCopy code
git fetch "$kit_remote" --tags --quiet
target_tag=$(git -C . tag -l 'v*' --sort=-v:refname | head -1)   # or: git ls-remote --tags
git verify-tag "$target_tag" 2>/dev/null && echo "TAG_VERIFIED" || echo "TAG_UNVERIFIED"

• TAG_UNVERIFIED (the kit currently ships annotated, not signed, tags) → continue, but downgrade every change to ask for this run and tell the user the target couldn't be cryptographically verified. Never auto-apply from an unverified source.

Step 3: Resolve the baseline (most-authoritative first)

The baseline is the kit version this install last synced to. Resolve in this order (H1):

1. Recorded commit — commit: in .kit-version, if present and reachable in the fetched history. Most authoritative.
2. Tag matching .kit-version version: (e.g. v0.1.0).
3. Merge-base — git merge-base HEAD "$kit_remote"/main.

If two layers disagree by more than zero commits, surface it ("recorded baseline v0.2.0 @abc123, but merge-base suggests v0.1.0 — using the recorded commit; N changes may already be present") and proceed with the most authoritative. Never silently pick.

Step 4: Compute the changeset + show the plan (dry-run is the default)

• changeset = entries in kit-changelog.yaml whose version is in (baseline, target], in order.
• For each, compute the predicted action without touching files: check conditions (presence), then detect (relevance), then apply the auto-allowlist ceiling (Step 6). Print the plan:

  vX.Y.Z will consider N changes: <id> → apply / skip (reason) / ask. Proceed?

• This --check view is the safe default entry point. Apply nothing until the user confirms.

Step 5: Work branch + tracker

bashCopy code
base_sha=$(git rev-parse HEAD)
git switch -c "kit-upgrade-$target_tag"

Write .upgrade-state.json: { work_branch, base_sha, baseline, target, entries: [{id, status}] } (status starts pending). This makes a re-run self-locating and resumable.

Step 6: Apply each entry (in order)

For each changeset entry — see references/apply-rubric.md for the full rubric:

1. conditions (presence gate) unmet → skip (record reason). default_action: skip-if-absent entries skip here when their feature/files are absent.
2. detect (relevance gate): read the local code (use detect_hint.grep/files to narrow if present). If the described pattern is gone (already fixed / diverged) → skip. Quote the evidence you checked.
3. Decide the action — default_action is a CEILING, not authority:
   • auto is honored ONLY if every path the change touches is in the auto-allowlist (config/**/*.yaml, dashboard/src/** non-config source, docs/**, CHANGELOG.md, .kit-version). If the change touches tools/**, Makefile, .claude/**, package*.json, *.config.*, *.sh, *.py, or .github/** → force ask regardless.
   • A secret-bearing path (config/secrets.yaml, config/go2rtc.yaml, config/esphome/**, .env*, anything in .claude/privacy-patterns) → never auto-apply/commit; present intent only (not the secret-laden hunk). Privacy-mode-aware: if privacy mode is on, list it but don't open it.
   • If the target tag was TAG_UNVERIFIED (Step 2) → everything is ask.
4. Apply via git 3-way merge using the entry's commits as ground truth:

   bashCopy code
   git apply --3way <(git show <commit>)        # inline conflict markers on divergence; never .rej, never --force
   

   On conflict → present the hunk + the entry's apply intent, and ask (never force). Adapt entity-specific bits (the install's IDs differ) per the apply guidance.
5. Validate (per area, infra-independent):
   • dashboard/lib change → cd dashboard && npx tsc -b --noEmit (no SSH).
   • config/ change → make validate only if config/configuration.yaml exists locally; else skip with a logged reason.
   • Never run make deploy-dashboard inside the loop — it rsync --deletes to the live HA box. Deploy is a separate, user-confirmed step after the upgrade.
6. Commit (if applied): stage only the changed paths (never git add -A); scan the staged diff for secrets (token/password/RTSP-cred patterns) and block the commit if any appear, routing that file to manual. Commit upgrade(<id>): <title>.
7. Record the outcome in .upgrade-state.json (applied / skipped / asked / needs-manual). Validate after each — no blind parallel apply.

Unattended runs: an ask or an unresolved conflict is a hard pause — record needs-human, continue the remaining auto-safe entries, and surface the queue at the end. Never auto-decide an ask.

Step 7: Finish

• Bump .kit-version (version: → target, commit: → target SHA) in the same commit as the last applied change, and only on a clean finish (every entry applied or deliberately skipped). If anything is needs-manual, leave the pointer behind and say so (staleness will still report "behind").
• Summarize — applied / skipped (+reason) / asked / needs-manual. No silent caps.
• Tell the user the work is on branch kit-upgrade-<target> for review, the rollback command (git switch <base-branch> && git branch -D kit-upgrade-<target>), and that deploying the dashboard (make deploy-dashboard) is a separate confirmed step.

Completion

Upgraded toward on branch kit-upgrade-<target>. Applied N, skipped M (already present / not installed), queued K for your decision. .kit-version advanced to (or: left at — K changes need manual review). Review the branch, then merge and make deploy-dashboard when ready. Rollback: git switch - && git branch -D kit-upgrade-<target>.

Troubleshooting