docs(incident): retroactive audit for direct-to-master commit 2fa97c26 (#670 )

2026-07-25 17:29:34 -05:00
1 changed files with 83 additions and 0 deletions
@@ -0,0 +1,83 @@
+# Incident #670: bare direct-to-master commit `2fa97c26` (retroactive audit)
+
+Status: verified; disposition recommendation: **accept as-is, no revert** (final
+disposition owned by controller per issue #670).
+
+## Summary
+
+Commit `2fa97c26fbda555a1a83930ca5fdcea9d8e47b50`
+(`fix(mcp): load dotenv relative to project root`) landed on `prgs/master`
+as a single-parent commit with no PR wrapper and no review record, bypassing
+the sanctioned issue → branch → PR → review → merge workflow. It was
+discovered during the PR #654 post-merge audit. PR #654 itself merged
+cleanly via the Gitea API and did **not** introduce this commit.
+
+## Verification evidence (acceptance criteria 1–3)
+
+- **AC1 — present on `prgs/master`: yes.**
+  `git merge-base --is-ancestor 2fa97c26fbda555a1a83930ca5fdcea9d8e47b50 prgs/master` → true.
+- **AC2 — no PR or review record: confirmed.**
+  The commit is a single-parent, non-merge commit sitting directly on
+  first-parent master between the #629 merge (`5ab5fe85`) and the #654
+  merge (`ec903b0d`). A PR landing on master produces a merge commit (or a
+  PR-linked head); neither exists here. The controller audit at issue-create
+  time also found no PR wrapper and no review record for this SHA.
+- **AC3 — changed files and diff summary: confirmed.**
+  `gitea_auth.py | 5 +++--` (+3/−2). Single parent
+  `5ab5fe8583c07134d55dadf09381aecb67df246e`. The change moves
+  `PROJECT_ROOT` derivation above `load_dotenv()` and loads
+  `.env` relative to the project root instead of the process CWD.
+
+## AC4 — why no immediate revert
+
+- The dotenv fix is intentional and required for correct runtime behavior:
+  without it, `load_dotenv()` resolves `.env` against the process working
+  directory, which breaks MCP server launches whose CWD is not the project
+  root.
+- The change is small (+3/−2), self-contained in `gitea_auth.py`, and has
+  been running on master without incident since 2026-07-10.
+- Reverting would re-introduce a real bug to remove a provenance defect —
+  the wrong trade. Provenance is repaired retroactively by this document,
+  issue #670, and the hardening landed under #671.
+- If the controller later judges the change unsafe, a separate
+  revert/repair issue is the sanctioned path (issue #670, recommended
+  disposition option 4).
+
+## AC5 — workflow-hardening linkage
+
+Prevention already landed: **issue #671** (closed)
+*“Block direct pushes to stable branches from MCP workflow sessions”*,
+implemented by commit `5933d87647656643a67a50331c4c7b06ea751dad`
+(`feat(guard): block direct stable-branch pushes from MCP workflow sessions`).
+
+Shipped guardrails include:
+
+- `gitea_record_stable_branch_push_attempt` — classifies proposed commands
+  for direct stable-branch push intent (`git push <remote> master`,
+  refspecs, `HEAD:master`, `--force`, dry-run intent, `:master` delete),
+  plus root/control-checkout local commits not carried by an issue branch,
+  and writes a durable `stable_branch_contamination` marker.
+- `gitea_audit_stable_branch_contamination` — reconciler-only audit/clear
+  path; a contaminated worker session cannot self-clear.
+- Review/merge/close/completion mutations fail closed while a
+  contamination marker is active.
+
+## AC6 — PR #654 was not the source
+
+- `2fa97c26` is the **first parent** of the #654 merge commit
+  `ec903b0d619e7a27d24aed272a890f4e5d381411`; it predates the #654 merge.
+- First-parent history `5ab5fe8..ec903b0`:
+  `2fa97c2 fix(mcp): load dotenv relative to project root` followed by
+  `ec903b0 Merge pull request 'feat: lifecycle role/hazard labels ... (#603)' (#654)`.
+- The #654 merger audit confirmed `ec903b0d` was a valid Gitea-API merge,
+  the `git push prgs master` attempt during that run was a no-op, and the
+  net change `2fa97c2..ec903b0` contained only the reviewed #603
+  lifecycle-label files.
+- Conclusion: #654 merged reviewed content only; the unauthorized-path
+  defect is solely the earlier bare commit `2fa97c26`.
+
+## Explicit non-actions (unchanged by this audit)
+
+- No revert of `2fa97c26`.
+- No force-push or history rewrite.
+- No master mutation from the audit session.