Prototype platform policy GitHub CLI scoping

[simple-agent-manager]

Summary

Add enforceable SAM platform policy for GitHub CLI installation-token scoping on agent profiles. When an agent profile has a custom GitHub CLI policy, the /git-token endpoint mints a scoped installation token restricted to specific permissions and the project repository only.

What changed

• Added githubCliPolicy column to agent_profiles (migration 0059) with shared types, API validation, D1 storage, and profile create/update/list round-tripping.
• Added profile UI controls in ProfileFormDialog for GitHub CLI token access: inherit installation permissions or restrict per profile (contents, pull_requests, issues, actions, packages).
• Added runtime token mint enforcement for task-linked workspaces: when a task has an agent profile with custom GitHub CLI policy, /git-token requests a GitHub installation token with repository_ids and narrowed permissions.
• Added fail-closed behavior for malformed stored policy JSON and for custom project-scoped policies when projects.githubRepoId is missing.
• Prototype route removed — only production UI surfaces ship.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test
• 34 unit tests pass (github-cli-policy + agent-profiles)

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — will deploy after merge to main
• Live app verified via Playwright — will verify after staging deploy
• Existing workflows confirmed working — will verify after staging deploy
• New feature/fix verified on staging — will verify by creating a restricted profile and dispatching an agent
• Infrastructure verification completed — N/A: no infra changes
• Mobile and desktop verification notes added for UI changes

Staging Verification Evidence

Previous staging deploy verified profile CRUD round-trip. Post-merge verification will exercise the full enforcement path: create a profile with restricted GitHub permissions, dispatch an agent, verify the agent cannot perform restricted operations.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified
• Accessibility checks completed
• Shared UI components used or exception documented
• Playwright visual audit run locally — previous session verified prototype at both viewpoints

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code
• If any gap exists between automated test coverage and full E2E, manual verification steps documented below

Data Flow Trace

1. User creates/updates agent profile with githubCliPolicy → apps/web/src/components/agent-profiles/ProfileFormDialog.tsx
2. API validates and stores policy → apps/api/src/services/agent-profiles.ts + apps/api/src/schemas/agent-profiles.ts
3. Task dispatched with profile hint → tasks.agent_profile_hint column
4. Workspace calls /git-token → apps/api/src/routes/workspaces/runtime.ts
5. Runtime resolves workspace → task → profile → policy → apps/api/src/services/github-cli-policy.ts:resolveWorkspaceGitHubTokenOptions()
6. Policy converted to GitHub API options → github-cli-policy.ts:toInstallationTokenOptions()
7. Scoped token minted → apps/api/src/services/github-app.ts:getInstallationToken() with repository_ids and permissions

Untested Gaps

• Direct workspace chat sessions (no task link) do not carry profile policy binding — they get full installation tokens. This is documented as a known production gap for follow-up.

Post-Mortem (Required for bug fix PRs)

N/A: not a bug fix

Specialist Review Evidence (Required for agent-authored PRs)

• All dispatched reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human

Reviewer	Status	Outcome
Local subagents	PASS	Reviewed implementation; fail-closed behavior added for invalid policy and missing githubRepoId

Exceptions (If any)

• Scope: Staging verification deferred to post-merge
• Rationale: Feature needs to be on staging to exercise the full enforcement path with a real agent
• Expiration: Will be verified immediately after merge and deploy

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

GitHub REST API: Installation token endpoint supports repository_ids and permissions parameters for scoping. Verified via GitHub docs.

Codebase Impact Analysis

• packages/shared — new GitHubCliPolicy types added to agent-settings.ts
• apps/api — migration 0059, schema update, agent-profiles service, github-cli-policy service, runtime route
• apps/web — ProfileFormDialog updated with policy controls, ProfileList shows policy badge

Documentation & Specs

N/A: This is the first enforceable policy slice. Architecture docs will be updated when the general policy framework is designed.

Constitution & Risk Check

Principle XI (No Hardcoded Values): Permission names mapped through permissionNames constant object, not hardcoded strings in multiple places. Default policy defined as DEFAULT_GITHUB_CLI_POLICY constant. No hardcoded URLs.

[sonarqubecloud]

Quality Gate passed

Issues
8 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.2% Duplication on New Code

See analysis details on SonarQube Cloud