Module gitinfo 

Git-derived recency and staleness — a port of the git touchpoint in src/asdecided/services/recency.py, per PORT-CONTRACT.d/08 §4.

Recency is derived from git log, never stored (ADR-045). This module shells out to the real git binary with the exact argv the oracle uses and reproduces its degrade-to-None posture: outside a repo, with no git binary, or for an untracked file, every value is None — no error crosses the boundary.

Landmines (PORT-CONTRACT.d/08 §4.2–4.3):

• git log --format=%cI renders the committer’s stored timezone offset and ignores TZ. last_committed is kept verbatim (offset preserved, never normalized to UTC).
• age_days = (reference - last_committed).days uses Python timedelta.days, which floors toward negative infinity (a future commit yields a negative age). This is whole-day truncation, not rounding.
• stale = age_days > threshold_days — strictly greater-than, so exactly at the threshold is not stale.
• Unknown date -> Staleness { None, None, None }.

Structs

Staleness

One artifact’s freshness: its verbatim last-committed date and the derived indicators. All-None when the date is unknown. Mirrors Staleness.

Constants

DEFAULT_STALE_AFTER_DAYS

The default “stale after” window (DEFAULT_STALE_AFTER_DAYS).

Functions

first_committed

The earliest commit time for path as the verbatim %cI string of the first non-blank line (committer offset preserved), or None when the file is untracked / uncommitted / outside a repo. Mirrors git log --reverse --format=%cI -- <path> (oldest first, first line is the creation commit) — used by the OKF export’s created field.

isoformat_roundtrip

Python datetime.fromisoformat(stamp).isoformat() round trip of a git %cI stamp: verbatim for the ±HH:MM form git emits; a trailing Z re-serializes as +00:00, a colonless ±HHMM gains its colon, ±HH becomes ±HH:00, and a space separator becomes T.

last_committed

The most recent commit time for path as the verbatim %cI string (committer offset preserved), or None when the file is untracked / uncommitted / outside a repo. Mirrors git log -1 --format=%cI -- <path>.

last_committed_for_paths

Last-committed time for each of paths (the raw recency primitive). Every path maps to None when directory is not a repo. Order preserved.

last_committed_for_paths_in_repo

Batched form of last_committed_for_paths for callers that already resolved the repository root. A newest-first git log --name-only walk assigns the first observed commit stamp to each path, reproducing git log -1 --format=%cI -- <path> without one subprocess per artifact.

parse_iso8601_epoch

Parse a strict ISO-8601 timestamp with an explicit offset (%cI form: YYYY-MM-DDTHH:MM:SS[.ffffff](Z|±HH:MM|±HHMM)) into Unix epoch seconds (UTC). Fractional seconds are ignored for whole-day math (git %cI has none). Returns None on any structural surprise (treated as “unknown”, matching the oracle’s fromisoformat ValueError -> None).

pathspec

path made relative to repo_root (via canonicalize, like Python’s Path.resolve()); if it lies outside the work tree, the absolute path is passed through unchanged.

repository_root

The work-tree root containing directory, or None if it is not a repo / git is unavailable. Mirrors git rev-parse --show-toplevel.

run_git_text

run_git with Python text=True universal-newline decoding (\r\n and lone \r → \n). The recency callers in this module only trim %cI stamps and the toplevel path, so they stay on the raw form; the decided-mcp provenance surface parses git show file content, where the normalization is load-bearing.

staleness

Staleness of one last-committed date against threshold_days, evaluated at reference_epoch_secs (Unix seconds, UTC). An unknown / unparseable date yields the all-None result.