Stamp audit runs and flag stale driftNotes (#341)

[ptr727]

Fixes #341. Both halves are the same failure mode: a point-in-time snapshot presented as current state, so an agent picking it up "fixes" what is already fixed.

1. Freshness signal on every run

spec/audit.py now prints:

audit run 2026-07-18T15:11:28Z | hub bd48caf

== HomeAutomation-Config (source-only; operational) @ main@6fadcbe ==
  clean (deterministic checks; the full operational verdict is AUDIT.md's)
...
Findings are a point-in-time snapshot: re-run this audit before acting on them, and quote the
run stamp above in any issue derived from it (AUDIT.md section 8).

• a run stamp (UTC + the hub commit the ground truth came from), and
• per repo, the exact commit read (@ <branch>@<sha>) - so a finding is attributable to a specific state.

AUDIT.md section 8 now requires anything derived from a run - a report, and especially an onboarding/conformance issue - to quote the stamp, and requires the agent picking that issue up to re-run the audit and act on the live result, not the pasted findings. Findings are evidence for why the issue was filed, never a claim about current state. That is exactly the #16 failure: two of three findings were already resolved at pickup.

2. driftNotes flagged when they outlive the deviation

A driftNote records a current deviation; once resolved it is deleted, not left describing finished work. audit.py now raises a drift finding when a repo audits clean but a note still asserts outstanding work (pending, not yet, missing, behind, owed, todo, still, absent).

The marker list is deliberately narrow and the check only fires on an otherwise-clean repo, so a note recording a permanent deviation ("no get-version-task; relies on validate-task") never trips it. Codified as setup.driftnotes.current.

The check earned its keep immediately

It caught a stale note I wrote myself for HomeAutomation-Config yesterday - "OWNER TASK OPEN: CODEGEN_APP_CLIENT_ID + CODEGEN_APP_PRIVATE_KEY not yet set in either secret store" - which the owner resolved (I verified the secrets and closed the downstream issue) but I never reconciled in the registry. Verified both secrets present in both stores, then removed the note entirely: with conformance complete it recorded no deviation at all.

Noise check: run across the fleet, the heuristic flagged exactly that one note.

Validation

spec/validate.py, markdownlint, editorconfig-checker clean; audit.py parses and runs; CRLF/LF preserved.

This lands before the fleet-wide audit sweep deliberately - it determines whether the issues that sweep produces are accurate on arrival.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds explicit freshness signals to spec/audit.py output (run stamp + per-repo audited commit) and codifies a low-noise heuristic to flag stale registry.driftNotes that still claim outstanding work when a repo otherwise audits clean. This strengthens the audit/onboarding workflow by making audit-derived findings clearly attributable to a point-in-time snapshot and reducing “already-fixed” churn at issue pickup.

Changes:

• Stamp audit runs with UTC time + hub SHA, and print per-repo @ <branch>@<sha> to attribute findings to an exact audited commit.
• Add a drift finding when driftNotes include “outstanding work” markers on a repo that otherwise audits clean; document the rule in AUDIT.md and spec/project-types.json.
• Remove a stale driftNotes entry from registry/repos.json that described already-resolved work.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
spec/project-types.json	Adds an intent check describing the new audit freshness/driftNotes behavior.
spec/audit.py	Implements run/repo stamping and adds the stale-driftNotes heuristic.
registry/repos.json	Removes a resolved/now-stale driftNote block for HomeAutomation-Config.
AUDIT.md	Documents the “stamp findings + re-run at pickup” requirement and driftNotes reconciliation expectation.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

spec/audit.py:235

• audited_sha stamping only handles groundTruthBranch values 'develop' vs everything-else (treated as main). Since registry/repos.schema.json allows any string for groundTruthBranch, a non-standard branch name would produce a misleading stamp (e.g. audits ref 'master' but prints master@). Stamp should come from the actual groundTruthBranch ref to avoid misattributing findings.

    # Stamp the commit actually read for the ground-truth branch. Never fall back to the other branch:
    # a stamp naming develop while carrying main's sha would misattribute every finding.
    ground_branch = branch_dev if ground == "develop" else branch_main
    audited_sha = (ground_branch or {}).get("commit", {}).get("sha", "")