Add timestamps to artifacts and auto-update baseline on drift

[devin-ai-integration]

Add timestamps to artifacts and auto-update baseline on drift

Summary

Two changes in this PR:

1. Timestamps & machine info on all generated artifacts

• docs/api_reference.md footer now includes generation timestamp and machine name
• artifacts/openapi_baseline.json is wrapped in a {"_meta": {"saved_at": ..., "saved_by_machine": ...}, "spec": {...}} envelope
• drift_summary.md and audit_report.md include detection/generation timestamps
• cmd_check has backward compatibility to read both old (raw spec) and new (wrapped) baseline formats
• New _timestamp() and _machine() helpers in guard.py

2. Pre-commit hook & CI auto-update baseline instead of blocking

• The pre-commit hook now runs drift_guard baseline automatically when drift is detected, stages the updated artifacts/openapi_baseline.json and docs/api_reference.md, and lets the commit proceed — instead of blocking with a "run baseline manually" message
• The CI workflow also runs drift_guard baseline when drift is detected instead of failing the job

Updates since last revision

• Fixed: cmd_check now wraps the updated baseline with _meta when drift is detected (commit a92436c), matching the behavior of cmd_baseline. Previously it wrote the raw spec, losing provenance info on subsequent runs.
• New (commit 030c542): Pre-commit hook and CI workflow auto-update baseline on drift instead of blocking/failing.

Review & Testing Checklist for Human

• CI auto-update doesn't persist: The CI workflow runs baseline to update files on the runner, and overrides the exit code to 0 so the job passes. But it does not commit or push the updated baseline back to the branch. This means CI will silently pass even when the committed baseline is stale. Decide whether CI should (a) still fail and require the developer to commit the fix, (b) auto-commit via actions/checkout + git push, or (c) keep current behavior where CI just doesn't block.
• Pre-commit hook silently stages files: The hook runs git add artifacts/openapi_baseline.json docs/api_reference.md during the pre-commit phase, adding files the developer didn't explicitly stage. Verify this is acceptable — if the baseline regeneration produces unexpected output, it gets committed without the developer reviewing it.
• Timestamps break deterministic regeneration: openapi_to_md.py's docstring promises "identical content when the schema hasn't changed." Every call to baseline now produces a different api_reference.md (different timestamp), creating noisy git diffs even when the API hasn't changed. Decide if this is acceptable or if timestamps should live elsewhere.
• Machine name in committed files: The committed baseline shows "saved_by_machine": "devin-box" — regenerating locally will change this to your hostname, creating a diff.
• Test plan:
  1. Pull the branch, start the server (uvicorn app.main:app --reload), install hooks (pip install pre-commit && pre-commit install)
  2. python -m drift_guard.guard baseline — verify baseline JSON has _meta and docs footer has timestamp
  3. Edit app/main.py to add a new field (e.g., age: int = 0 to User model), stage it with git add app/main.py, and run git commit -m "test" — verify the pre-commit hook auto-updates baseline and docs, stages them, and lets the commit proceed (check git log and git diff HEAD~1 to confirm the baseline was included in the commit)
  4. Delete artifacts/openapi_baseline.json, copy in an old baseline (raw spec without _meta), run check — verify backward compatibility works

Notes

• No unit tests were added for the new timestamp/machine helpers or the backward-compatible baseline parsing.
• Ruff lint passes clean.
• The pre-commit hook starts a temporary server on port 18199 — if that port is in use, the hook will fail and ask for manual intervention.

Link to Devin run: https://app.devin.ai/sessions/23d1e596e5f845ec8c47886363e9b2b8
Requested by: @justinemach

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring