# Local Repo Update Audit

Audit a local installation of a GitHub project against its current upstream repository. This is a **pre-update audit only**.

## Inputs

* **Repository URL:**
* **Local install path:** `unknown` if unknown
* **Project name:**

If both Repository URL and Local install path are missing or unknown, stop and request at least one. Never guess either.

## Hard Rules

1. **Make no changes.** Do not install, update, migrate, restart, activate, overwrite, delete, or otherwise modify local or remote state.
2. You may run read-only inspection commands without approval, including `git status`, `git log`, `git diff`, `git remote -v`, `git rev-parse`, `git describe`, file listings/reads, config/lockfile inspection, and process/service status checks.
3. Inspect upstream only through read-only methods such as GitHub API/web requests, `git ls-remote`, or equivalent. Do not run a local `git fetch`, `pull`, `checkout`, or other command that changes repository state.
4. Every **local** factual claim must be supported by a command actually run this session. Every **upstream** factual claim must be supported by data actually retrieved this session. Cite the command, API request, or source beside the claim.
5. If something cannot be verified, label it **unverified**. Never substitute memory, training data, convention, or assumption.
6. The final update plan may contain commands that would modify state, but **recommend them only. Do not execute them.**
7. Report actionable findings only. Omit empty categories. Investigate beyond the scope below only when a finding or failed verification makes it necessary, and state why.

## Inspect

**Local**

* Install path, branch, commit/version/tag
* Uncommitted changes and important untracked files
* Config, environment, dependency, and lockfiles
* Service/daemon/CLI/runtime activation method
* Local patches or customizations that an update could affect

**Upstream**

* Repository URL and default branch
* Latest commit and release/tag
* Changes since the installed local revision
* New or changed features, commands, files, dependencies, config/setup requirements, services/background workers
* Breaking changes, migrations, deprecations, compatibility or security/stability notes
* Relevant README, changelog, release-note, documentation, or issue guidance

**Compare**
Identify upstream changes not present locally and their practical effect, including files/configs/services that may be added, changed, removed, overwritten, or invalidated.

## Output

# [PROJECT NAME] Update Audit

### Status

State **complete**, **partially complete**, or **blocked**, with the reason if not complete.

Also state explicitly:

> No changes were made. No update was installed. No services were restarted or activated.

### Current Local State

Summarize the verified local installation, including revision, working-tree state, relevant config/runtime details, and customizations requiring protection. Cite evidence inline.

### Current Upstream State

Summarize the verified current repository state, latest revision/release, and update-relevant documentation. Cite evidence inline.

### Updates Not Installed Locally

| Update / Change | What Changed Upstream | Installed Locally? | Why It Matters | Risk |
| --------------- | --------------------- | ------------------ | -------------- | ---- |

Combine minor related changes when useful.

### Files, Configs, and Services at Risk

List only items that could realistically be overwritten, invalidated, migrated, or otherwise affected, including local patches, user data, credentials, runtime paths, service definitions, or custom behavior.

### Recommended Update Plan

**Do not execute.** Give the shortest safe step-by-step plan covering:

* backup/preservation
* update/install method
* dependencies
* config or migrations
* activation/restart
* validation
* rollback

For each step, identify the executor: **user**, **agent**, or **third-party tool/service**.

### Recommendation

Choose exactly one:

* **Update now**
* **Update after backup**
* **Update after resolving local changes**
* **Do not update yet**
* **Manual review required first**

Justify it in 2–3 sentences using specific verified findings from this audit.

### Approval Needed

> No changes have been made. This was a pre-update audit only. I am waiting for approval before installing, updating, restarting, activating, migrating, overwriting, or deleting anything.

## Failure Conditions

The audit is wrong if it:

* invents or assumes a repo, path, revision, config, or upstream fact;
* states an uncited local/upstream fact as verified;
* changes any local or remote state during inspection;
* executes any command from the proposed update plan;
* gives a recommendation not traceable to verified findings; or
* pads the report with empty boilerplate instead of omitting irrelevant sections.