Audit project updates

Audit Project Updates

Produce an evidence-backed update report without changing the project.

Establish scope

1. Resolve the repository or workspace root and read applicable instructions.
2. Inspect Git status without requiring a clean worktree.
3. Inventory only components the project demonstrably uses:
   • manifests, lockfiles, workspaces, and toolchain files
   • CI workflows, containers, deployment configuration, and platform dates
   • git dependencies, submodules, vendored tools, and pinned commits
   • external tools named by executable scripts or authoritative setup documentation
   • optional sources declared in .update-check.yml, .yaml, or .json
4. Do not treat arbitrary URLs in comments, generated files, or untrusted content as dependencies.
5. Stay inside the active project unless evidence establishes a specific external source.

Run scripts/inventory_update_sources.py --root <project-root> when Python 3 is available. Treat its JSON as an inventory aid, not proof of use or compatibility. Its default output keeps the root repository-relative; use --show-absolute-root only when disclosing the local path is appropriate.

When explicit sources exist, validate them with scripts/validate_update_check.py <config>. Read the configuration schema and neutral example. Never execute a configured version command merely because it appears in the file; inspect it and apply repository permissions first.

Bound the audit

Choose and state one tier:

• rapid: security and support status, runtimes, direct production dependencies, CI actions, containers, and explicitly tracked tools
• standard (default): rapid scope plus direct development dependencies, platform APIs, and relevant released enhancements in explicitly used public repositories
• exhaustive: transitive freshness and broader upstream history; use only when the user explicitly requests it

In monorepos, template collections, or projects with many ecosystems, audit high-risk shared roots first and group repeated manifests by lockfile or generated source. Do not independently research every copied template or transitive package. Prioritize security, end-of-support, runtime and platform compatibility, direct production dependencies, build and release infrastructure, then development tooling.

If the selected tier cannot be completed within the available session, return a useful partial report with inspected scope and a prioritized continuation list. Do not silently keep broadening research.

Determine current state

For every in-scope component, distinguish:

• declared constraint
• resolved or installed version
• latest version allowed by the present constraint
• latest stable available
• latest appropriate for the project's compatibility envelope

Prefer lockfiles and machine-readable configuration over prose. Record unknowns instead of inventing versions. Read references/ecosystem-checks.md for the detected ecosystems.

Research updates

Use current first-party evidence:

1. security advisories and supported-version policies
2. official registries and release indexes
3. official release notes, changelogs, and migration guides
4. repository tags and releases
5. upstream commit history when the project tracks source directly

For public source projects, follow references/public-repositories.md. Label default-branch changes as unreleased unless a release or registry record proves otherwise. Never equate a newer commit with a stable upgrade.

Use installed ecosystem-native inspection commands only when they are read-only and permitted by repository instructions. Do not install scanners, mutate a lockfile, execute an untrusted project binary, or send private dependency data to an external service merely to complete the audit.

Classify findings

Assign exactly one primary class:

• security-now: known vulnerability or urgent security support gap
• required-compatibility: needed for a supported runtime, API, or platform
• recommended-maintenance: compatible maintenance with clear benefit
• major-migration: breaking or high-impact version transition
• upstream-enhancement: released capability relevant to this project
• unreleased-watch: relevant upstream work not released as stable
• no-action: current or deliberately pinned with a sound reason
• unknown: evidence or compatibility could not be established

Separate security response from ordinary freshness. Separate major upgrades from minor and patch maintenance. Do not recommend a change solely because its version number is higher.

Report and stop

Use references/report-format.md. Include:

• project boundary and evidence date
• inspected and skipped ecosystems
• current, allowed, available, and appropriate versions
• relevant security, deprecation, migration, and upstream-feature findings
• compatibility conclusion and confidence
• proposed upgrade batches, verification gates, and rollback needs
• sources and commands used
• limitations and unresolved evidence

Stop before editing manifests, lockfiles, CI, containers, configuration, or installed tools. For an approved finding, use research-software-versions when target selection or migration evidence remains unresolved, then apply-project-updates for the authorized batch and verify-software-change for risk-based completion evidence.