docs(#5311): add ADR 0073 for named mint privilege levels

[fullsend-ai-coder]

Summary

• Add ADR 0073 deciding the mechanism for named privilege levels (read, write) under agent roles, covering mint API, custom role config, client support, acquisition semantics, and harness privilege_levels flag
• Update docs/architecture.md with the decision under both Agent Identity Provider and Agent Harness sections

Related Issue

Closes #5311

Blocks: #2821 (human-gated permission adjustments ADR)
Implementation follow-on: #2823 (mint implementation)
Topic: #5312

Changes

ADR 0073 (docs/ADRs/0073-named-mint-privilege-levels.md)

New ADR covering seven required areas:

1. Role levels — ordered named levels per role (read default, write as current max permissions)
2. Mint API — optional level field in token requests (default read)
3. Custom roles — backward-compatible CUSTOM_ROLE_PERMISSIONS extension with auto-detected multi-level JSON shape
4. Clients — mintclient and CLI support for level selection
5. Acquisition semantics — harness is the sole caller that selects privilege levels per phase
6. Write level definition — write equals current max permissions; falls back to read when not defined
7. Harness privilege_levels flag — maps run phases to levels with default key; backward-compatible default: write when omitted

docs/architecture.md

• Added named privilege levels decision to Agent Identity Provider section
• Added phase-scoped privilege levels decision to Agent Harness section

Testing

• ADR file exists at docs/ADRs/0073-*.md with status: Accepted
• ADR is concise (89 lines of content excluding frontmatter, under 100-line limit)
• docs/architecture.md updated with the decision
• All seven required areas covered in the Decision section
• write level defined as current max permissions, with fallback to read
• privilege_levels harness flag with default key and backward-compatible default: write fallback
• Cross-references to docs: ADR for human-gated permission adjustments and threat model #2821, mint: implement named privilege levels under agent roles #2823, and Topic: least-privilege mint tokens for different agent run phases #5312 present
• Secret scan passed
• YAML frontmatter valid; relates_to references verified
• No trailing whitespace; title number format correct (no leading zeros)

Checklist

• Changes follow ADR writing conventions per skills/writing-adrs/SKILL.md
• ADR number 0073 chosen to avoid collision with in-flight PRs (docs: ADR 0071 — Auto-merge #2791 uses 0071, docs(#4718): add ADR 0072 for the pre-script skip-flag convention #5016 uses 0072)
• Frontmatter status matches body status (Accepted)
• relates_to references valid problem docs (security-threat-model, agent-architecture)
• Secret scan passed (scan-secrets --staged)

---

Closes #5311

Post-script verification

• Branch is not main/master (agent/5311-named-mint-privilege-levels)
• Secret scan passed (gitleaks — 24d41836a2de6b7abaa6b20be2bdac9a61f7e0d3..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 5:45 PM UTC · Completed 5:59 PM UTC
Commit: eae5202 · View workflow run →

[github-actions]

Site preview

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

Commit: 195ec7d9e8e3c4df9b0cade12dd162267587f137

[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/0073-named-mint-privilege-levels.md:44 — The ADR defines write as "the permission set currently granted by each built-in role" but does not specify how the read permission set is derived for built-in roles. Since the superset invariant requires read to be a subset of write, the derivation rule matters for implementation. Additionally, custom roles using the flat CUSTOM_ROLE_PERMISSIONS format have their permissions interpreted as the read level, meaning they would have no write level unless they use the multi-level format.

• [edge-case-handling] docs/ADRs/0073-named-mint-privilege-levels.md:59 — The CUSTOM_ROLE_PERMISSIONS auto-detection mechanism does not explicitly state whether mixed formats (some roles flat, some multi-level) within a single JSON value are supported.

[ifireball]

/fs-fix the fullsend-ai-review comments according to the following:

The "read" permission levels for the built-in roles are determine by taking the current permissions sets and removing a the *:write permissions.

We will allow mixed format CUSTOM_ROLE_PERMISSIONS since we can write the detection code to allow it.

The following statement in the "consequences section is inaccurate:

The mint API remains backward-compatible; omitting level produces the same tokens as today.

The mint API itself will default to "read" level and therefore would return narrower tokens then what would be returned today

The same goes for the combination of the API and the clients

Only the use with harness files that omit privilege_levels remains compatible because of the default to write.

[fullsend-ai-coder]

🤖 Fix · ❌ Terminated · Started 4:04 AM UTC · Ended 4:11 AM UTC
Commit: 3d48dce · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed all three review findings from human instruction on ADR 0073: (1) specified how built-in role read levels are derived (removing *:write permissions from current set), (2) clarified that CUSTOM_ROLE_PERMISSIONS supports mixed format within a single value with per-role detection, (3) corrected the inaccurate backward-compatibility statement — the mint API defaults to read (narrower tokens than today), and only harness-level privilege_levels omission preserves backward compatibility via the write default. Both docs/ADRs/0073-named-mint-privilege-levels.md and docs/architecture.md were updated consistently.

Fixed (3):

1. *Built-in role read levels should be derived by removing :write permissions (docs/ADRs/0073-named-mint-privilege-levels.md): Added explicit statement in Role levels section that read level for each built-in role is derived by taking the role's current permission set and removing all *:write permissions. Updated architecture.md summary to match.
2. Allow mixed format CUSTOM_ROLE_PERMISSIONS with per-role detection (docs/ADRs/0073-named-mint-privilege-levels.md): Changed 'auto-detects the format by checking' to 'auto-detects the format per role by checking'. Added paragraph stating mixed format is allowed within a single CUSTOM_ROLE_PERMISSIONS value. Updated architecture.md to mention mixed format support per role.
3. Backward-compatibility statement in Consequences is inaccurate (docs/ADRs/0073-named-mint-privilege-levels.md): Replaced 'The mint API remains backward-compatible; omitting level produces the same tokens as today' with accurate statement: mint API defaults to read, producing narrower tokens. Clarified that only harness files omitting privilege_levels remain compatible because the harness defaults to write. Updated architecture.md to note omitting level produces narrower tokens.

Tests: passed

_{Updated by fullsend fix agent}

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[waynesun09]

Reviewed by 3-agent squad (Claude, Grok). No blocking findings after verification — all findings downgraded to LOW after confirming design intent with author:

• Wording: "removing all *:write permissions" reads as stripping scopes entirely in GitHub API terms; implementation will downgrade to read — consider clarifying in the ADR text
• Migration: mint API default-to-read affects non-harness callers (reconcileMintToken, mint-token CLI, e2e); coordinate in #2823/#2826
• Phase coverage: validation_loop inherits runtime level — worth a sentence clarifying this is intentional
• Format detection: levels key as implicit discriminator is fine for now; note as reserved if future forges collide

All cross-references verified (ADRs 0007/0059/0060/0068/0070, issues #2821/#2823/#2826/#5311/#5312, problem docs). Architecture.md updates accurately reflect the ADR.

[ifireball]

/fs-fix deal with the following comments by @waynesun09

Reviewed by 3-agent squad (Claude, Grok). No blocking findings after verification — all findings downgraded to LOW after confirming design intent with author:

* **Wording:** "removing all `*:write` permissions" reads as stripping scopes entirely in GitHub API terms; implementation will downgrade to `read` — consider clarifying in the ADR text

* **Migration:** mint API default-to-`read` affects non-harness callers (`reconcileMintToken`, `mint-token` CLI, e2e); coordinate in #2823/#2826

* **Phase coverage:** `validation_loop` inherits `runtime` level — worth a sentence clarifying this is intentional

* **Format detection:** `levels` key as implicit discriminator is fine for now; note as reserved if future forges collide

All cross-references verified (ADRs 0007/0059/0060/0068/0070, issues #2821/#2823/#2826/#5311/#5312, problem docs). Architecture.md updates accurately reflect the ADR.

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 7:14 PM UTC · Completed 7:20 PM UTC
Commit: 02a0757 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 2 (human-triggered)

Addressed all 4 review findings from @waynesun09. Clarified wording on permission downgrading, named specific non-harness callers affected by default-to-read, documented validation_loop phase inheritance, and noted levels key is reserved for format discrimination. Updated both ADR 0073 and docs/architecture.md.

Fixed (4):

1. *Wording: 'removing all :write permissions' ambiguous in GitHub API terms (docs/ADRs/0073-named-mint-privilege-levels.md): Changed 'removing all *:write permissions' to 'downgrading all *:write permissions to their read counterparts' with an example (contents: write becomes contents: read). Also updated the matching summary in docs/architecture.md.
2. Migration: mint API default-to-read affects non-harness callers (docs/ADRs/0073-named-mint-privilege-levels.md): Replaced generic 'Direct API callers and mint clients' with explicit mention of reconcileMintToken, mint-token CLI, and e2e test helpers as affected callers. Added coordination reference to mint: implement named privilege levels under agent roles #2823/harness: separate permission profiles per run phase #2826.
3. Phase coverage: validation_loop inherits runtime level (docs/ADRs/0073-named-mint-privilege-levels.md): Added a sentence in the privilege_levels section clarifying that phases not explicitly listed (such as validation_loop) inherit the runtime level, since they execute within the runtime phase and share its security context.
4. Format detection: levels key as implicit discriminator could collide (docs/ADRs/0073-named-mint-privilege-levels.md): Added parenthetical note that 'levels' is reserved for format discrimination and role definitions must not use it as a permission name.

Tests: passed

_{Updated by fullsend fix agent}