ci(pkg): gate the public API surface and document its stability policy

[devlikebear]

Part of #919. Phase 2 of the public library boundary track. LP-010.

Prerequisite: #928 (LP-009).

Summary

Make breaking changes to pkg/* visible in review, and state in writing what consumers may rely on.

Problem

After #928 the public API owns its types, but nothing stops it from changing silently. Today a rename inside pkg/llm breaks every external consumer with no signal at PR time — the module is v0.35.0, so semver permits it, but a real consumer exists and "semver permits it" is not a workflow.

docs/public-agent-packages.md describes the packages and their boundaries but says nothing about stability: no deprecation policy, no statement of what v0 means here, no guidance on which packages are safe to build on.

examples/min-agent exercises the surface but is only an example — it is not a gate, and it uses a scripted client, so it would not catch a signature change in NewProvider.

Scope

• Add an API surface snapshot for pkg/* — generated exported-identifier listing, checked in, diffed in CI. A changed snapshot fails until the file is updated in the same PR, making the break explicit in review rather than blocking it.
• Add a compile-only consumer test that imports every public package and touches its main entry points, so signature changes fail the build.
• Wire both into the pr-diff job alongside the existing preflight targets.
• Write the stability policy into docs/public-agent-packages.md: what v0 means, deprecation before removal, which packages are stable vs experimental, how breaking changes are announced.
• Note the actual consumer (linetta) in the doc so the cost of a break is visible to whoever proposes one.
• Record the dependency-weight expectation from refactor(tool): split internal/tool into core primitives and TARS app tools #927 as a documented property, not an accident.
• Expand examples/ beyond the scripted client so the documented "minimal agent shape" is compiled against the real provider constructor.

Acceptance Criteria

• Adding, removing, or changing an exported identifier in pkg/* fails CI until the snapshot is updated.
• The gate runs on pull requests and reports which identifiers changed.
• The stability policy is published and linked from the README.
• make exposes a target to regenerate the snapshot locally.
• A deliberate breaking change produces a readable diff, not an opaque failure.

Validation

• Introduce a breaking change locally and confirm CI fails with a useful message
• Confirm a non-breaking addition fails only until the snapshot is regenerated
• make test
• make lint-diff
• make ci-static-analysis-check

Out of Scope

• Declaring v1.0.
• Publishing the packages as a separate module. See chore(arch): enforce layer boundaries in-repo and defer the multi-repo split #930.