chore(agent): self-update versioning rule + bump 0.5.24 → 0.5.25

[lotgon]

What

• Add src/agent/AGENTS.md — directory-scoped rule: HsmAgent VERSION is the self-update delivery key. Any change that alters the shipped agent binary's observable behavior — including native-collector changes compiled into the agent — must bump the patch version in the same PR, or the strictly-greater semver check in src/agent/src/update_checker.cpp never delivers it to deployed agents.
• Bump project(HsmAgent VERSION 0.5.24 → 0.5.25).

Why

The #1221 collector logging events changed the agent binary (new lifecycle / registration / send-fail log lines) but left HsmAgent VERSION at 0.5.24. The server advertises 0.5.24, deployed agents run 0.5.24, and GET /api/agent/version self-update only ships a strictly greater version — so 0.5.24 == 0.5.24 → "already up to date", and the new build is undeliverable except by a manual binary swap.

This PR applies the new rule retroactively: bumping to 0.5.25 lets already-running agents pick up the #1221 logging via their normal self-update path.

Notes

• No behavior change beyond the version constant; the rule doc is the substance.
• Root AGENTS.md ## Versioning left as-is — this refinement is directory-scoped to src/agent/ per the AGENTS.md nesting convention.

🤖 Generated with Claude Code

[github-actions]

PR #1222 Review — chore/agent-selfupdate-versioning

Summary

Two changes:

1. Bump project(HsmAgent VERSION 0.5.24 → 0.5.25) in src/agent/CMakeLists.txt.
2. Add a new directory-scoped src/agent/AGENTS.md documenting the self-update versioning rule.

This is a low-risk documentation + version-bump PR. I verified every technical claim in the new doc against the actual code, and they all hold. No bugs, security, or performance issues found.

Verification of the documented behavior

The new AGENTS.md makes several concrete claims about the self-update mechanism. I traced each end-to-end:

• ✅ Compile-time version. CMakeLists.txt:120 sets HSM_AGENT_VERSION="${PROJECT_VERSION}", so bumping project(... VERSION ...) propagates as documented.
• ✅ Strictly-greater semver, major → minor → patch. src/agent/src/update_checker.cpp:70 IsNewer() compares major, then minor, then return candidate.patch > current.patch — exactly as described. A same-version rebuild yields IsNewer == false → "already up to date" (update_checker.cpp:525), confirming the doc's core rationale.
• ✅ GET /api/agent/version manifest. update_checker.cpp:496 requests it; AgentController.cs:95 serves { version, sha256, updateEnabled }, reading wwwroot/agent/version.txt (AgentController.cs:185) — matching the doc's "staged wwwroot/agent/" claim.
• ✅ The bump actually reaches the channel. .github/workflows/agent-windows-build.yml:100-101 greps the version straight out of project(HsmAgent VERSION ...) into staging/version.txt, which is what the server advertises. So 0.5.25 will correctly propagate CMake → version.txt → manifest → agent comparison.
• ✅ feat(native): collector logging parity — built-in file logger + events + tests #1221 precedent. PR feat(native): collector logging parity — built-in file logger + events + tests #1221 (feat/native-collector-logging) is merged on master with HsmAgent VERSION still at 0.5.24, exactly as the doc states. This bump to 0.5.25 is therefore the legitimate delivery vehicle for those already-merged collector changes — a well-justified reason to bump.
• ✅ Root-rule override. The doc correctly overrides the root AGENTS.md:113 "bump only when preparing a release" rule for this directory, and the "Exception" clause (doc-only / test-only / behavior-neutral) keeps it internally consistent — this PR's own bump ships the real feat(native): collector logging parity — built-in file logger + events + tests #1221 behavior change, not the doc.
• ✅ All relative links resolve (../../AGENTS.md, CMakeLists.txt, src/native/collector, src/update_checker.cpp).

Observations (non-blocking)

1. New coupling worth guarding in CI. The policy — "any collector change that alters the shipped binary must bump HsmAgent VERSION" — is sound, but it relies entirely on reviewers remembering it, and the feat(native): collector logging parity — built-in file logger + events + tests #1221 miss shows how easily it's forgotten. Consider a CI guard: a PR touching src/native/collector/** or src/agent/src/** fails unless src/agent/CMakeLists.txt's version line changed. It would need an opt-out label/marker for the documented test-only/doc-only exception to avoid false positives, but it would make the rule self-enforcing rather than aspirational.

2. Minor paraphrase gap. The doc paraphrases the root rule as "bump only when preparing a release"; the root rule (AGENTS.md:113) also includes "…or when the task explicitly asks for it." Not misleading, just slightly incomplete — optional to tighten.

Verdict

Accurate, well-scoped, and correctly wired through the build/self-update pipeline. Recommend merge; consider the CI guard (#1) as a follow-up so the newly documented rule can't be silently skipped again.