fix(contexts): stabilize FileManifest identity and timestamps

[ananjan-nandi-9]

Summary

• Records FileManifest.created_at as a timezone-aware UTC timestamp.
• Excludes capture time from FileManifest equality and hashing so identical snapshots have stable identity.
• Adds regression coverage and an Unreleased changelog entry.

Motivation / Context

A manifest capture timestamp is provenance metadata, not part of the identity of the captured file snapshot. Including it in equality and hashing makes otherwise identical manifests compare unequal merely because they were captured at different times, while a naive timestamp also leaves timezone interpretation ambiguous.

Delta Breakdown

1. Stabilize manifest semantics. created_at now uses datetime.now(timezone.utc) and is marked compare=False, hash=False. Reviewers should verify that capture time remains serialized and inspectable while no longer affecting snapshot identity.
2. Lock the contract with tests. Regression tests verify equal hashes/equality across different timestamps and verify that the default timestamp is UTC-aware.
3. Document the user-visible fix. The Unreleased changelog explains the stable-identity and timezone behavior.

Entry Point

FileManifest in simple_workspace/manifest.py → equality/hash regression tests in test_simple_workspace_content_hash.py → Unreleased changelog entry.

The affected API surface is construction, comparison, and hashing of FileManifest instances; serialization fields remain present.

Review Guide

The key judgment is whether created_at should be treated as metadata rather than snapshot identity. The principal compatibility change is that manifests differing only by capture time now compare equal and produce the same hash. No architecture or durable-runtime changes are included.

Validation

• Static checks: Ruff check and format check passed for changed Python files; uv lock --check passed.
• Type checks: Not run separately; the complete contexts package test suite exercises construction and typing-sensitive model paths.
• Tests: All 270 tests in the contexts package passed.
• Targeted/manual validation: Regression coverage confirms UTC awareness and comparison/hash independence from created_at.
• Not run: The shared make baseline completed 27 tests with 5 skips, then hit its existing Linux/macOS mismatch because the test config selects the APFS-only clonefile backend.

Documentation / Changelog / Decisions

Updated the Unreleased Fixed section in shepherd/packages/meta/CHANGELOG.md. No architecture decision record is needed for this contained dataclass semantics fix.

Risk / Rollback / Migration

Risk is low but behavioral: code using manifests as dictionary keys or set members will now coalesce snapshots that differ only by capture time. That is the intended identity contract. Rollback is a normal revert; no data migration is required, and serialized manifests retain created_at.

Follow-ups

None.

[cloudflare-workers-and-pages]

Deploying shepherd-agents-docs with    Cloudflare Pages

Latest commit:	b05b733
Status:	✅  Deploy successful!
Preview URL:	https://1db1ea62.shepherd-agents-docs.pages.dev
Branch Preview URL:	https://fix-file-manifest-identity.shepherd-agents-docs.pages.dev

View logs