docs(#2821): add ADR 0074 for human-gated permission adjustments

[fullsend-ai-coder]

Summary

Adds ADR 0074 recording the design decision for human-gated permission adjustments — the authorization path that allows agents to receive elevated permissions (e.g., workflows: write) only when a repository collaborator explicitly grants approval via forge-native labels.

Related Issue

Closes #2821

Changes

• New ADR 0074 (docs/ADRs/0074-human-gated-permission-adjustments.md): Records:
  • Layer boundaries: CLI policy (labels, collaborator checks, stale invalidation) → mint mechanics (mechanical elevation merging) → deterministic automation (privileged pushes outside sandbox)
  • Threat model: TOCTOU between authorization and mint, post-grant injection expanding scope, post-grant injection via privileged tools
  • Design choice: Human authorization over automated repo-readiness gating; docs(adr): propose ADR 0044 gate workflows:write on repo secret allowlist #1739 approach superseded
  • Authorization flow: workflow-change-needed / workflow-change-allowed label pair with stale invalidation
• docs/architecture.md: Added "Decided" entry under Agent Identity Provider for the authorization gate pattern, referencing ADR 0074

Builds on ADR 0073 (named mint privilege levels, merged via PR #5328). Uses the closed PR #2548 draft ADR as reference material.

Testing

• ADR linters pass (lint-adr-status, lint-adr-numbers, lint-adr-frontmatter)
• gitlint passes
• Secret scan passes
• make lint could not run (sandbox network policy blocks pre-commit's git fetch); post-script runs authoritative pre-commit on the runner

---

Closes #2821

Post-script verification

• Branch is not main/master (agent/2821-adr-human-gated-perms)
• Secret scan passed (gitleaks — 8e3d60fa6cd20b8a7410b5533c63200689de56d6..HEAD)
• PR body secret scan passed (gitleaks — no-git)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:51 AM UTC · Completed 11:06 AM UTC
Commit: 1b27916 · View workflow run →

[github-actions]

Site preview

Preview: https://cf2ceb99-site.fullsend-ai.workers.dev

Commit: 1b279163c7dd6533588b0e1987705fc87864482e

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

Low

• [internal consistency] docs/ADRs/0074-human-gated-permission-adjustments.md:52 — The TOCTOU mitigation states "Authorization check and mint request occur in a single CLI invocation" but the Layer Boundaries section describes the CLI policy layer and mint mechanics layer as separate components with separate responsibilities. The follow-up sentence clarifies the window is bounded by "a single workflow step, not by human reaction time," which is a different (and weaker) claim than a single CLI invocation. Consider clarifying whether fullsend auth check both verifies authorization and calls the mint API atomically in one process, or whether these are two sequential calls within one workflow step.

---

Labels: PR adds ADR 0074 covering mint permission elevation design and updates architecture docs

[fullsend-ai-review]

[low] internal consistency

The TOCTOU mitigation states "Authorization check and mint request occur in a single CLI invocation" but the Layer Boundaries section describes the CLI policy layer and mint mechanics layer as separate components with separate responsibilities. The follow-up sentence clarifies the window is bounded by "a single workflow step, not by human reaction time," which is a different (and weaker) claim than a single CLI invocation. Consider clarifying whether fullsend auth check both verifies authorization and calls the mint API atomically in one process, or whether these are two sequential calls within one workflow step.

[ifireball]

Parking as draft for now.

This ADR for human-gated permission adjustments should wait on the mint named privilege-levels implementation (#2823 under topic #5312). That design should land first so phase-differentiated / elevated tokens are not invented ad hoc here.

Underlying issue #2821 is now blocked by #2823.

[github-actions]

This pull request has been automatically marked as stale because it has not had any activity in the last month. It will be closed in 2 weeks if no further activity occurs. Remove the stale label to reset the inactivity timer.