docs(specs): prebuild for #56 Forgejo MCP identity split per agent v0 #367

Merged

pdurlej merged 1 commit from claude/fork-A2-forgejo-mcp-identity-split into main

2026-05-23 09:19:32 +02:00

claude commented

2026-05-18 08:17:56 +02:00

Collaborator

Summary

Fork-A2 prebuild for issue #56 (operator Signal report 2026-05-04). Today's Forgejo MCP layer defaults to operator pdurlej admin identity for tool calls — even when active session is a cousin. Misattribution + admin token exposure surface too wide + reviewers can't tell which cousin performed an action.

What's in

Spec Kit (6 files in docs/specs/forgejo-mcp-identity-split-v0/):

00-constitution.md — 9 principles (P1-P9: one default identity per cousin, admin disabled by default, fail-closed on ambiguity, composes with Agent Access Plane, iskra deferred to v0.1) + non-goals + sacred boundary statements
01-specify.md — 9 machine-checkable acceptance criteria (A1-A9) + smoke contract
02-plan.md — 10 design decisions with alternatives compared (D1: thin router in platformctl; D2: PAT backing via Access Plane capability handle; D4: env-flag + typed confirmation for admin break-glass; D5: iskra deferral; D6: DeepSeek read-only-only)
03-tasks.md — 4 slices (a/b/c/d); ~1850 LOC; ~10-14h codex; tier per slice (Lite/Full)
04-implement-notes.md — 12 gotchas + prior art + composition notes
README.md — overview

Execution prompt (prompts/codex-forgejo-mcp-identity-split.md):

Safety / production boundary section (per Codex 2026-05-17 feedback + PR #326 pattern)
Pre-flight identity check
Per-slice instructions with branch / tier / tasks / acceptance
ADR-0018 stop conditions (NO admin-fallback workarounds, NO accept-workaround outcomes)
Reporting format + cousin coordination rules

Composes with

PR #323 Agent Access Plane v0 — sibling; this v0's router consumes Access Plane session-scoped capability handles for per-cousin PAT delivery
ADR-0003 (Agent Access Plane), ADR-0005 (Coordination lanes), ADR-0010 (Cousin taxonomy), ADR-0017 (No stacked), ADR-0018 (Fix root causes)
PLATFORM_CHARTER §3 identity-isolation; AGENTS.md § Identity-isolation

Key principles preserved (durable for context-compressed cousins)

P2: admin MCP enabled_by_default: false — explicit break-glass only (env flag + typed confirmation + audit log)
P6: fail-closed on identity ambiguity — NEVER fall back to admin
P9: iskra integration deferred to v0.1; sacred-path boundary respected; v0 publishes contract but does not modify iskra runtime

Per ADR-0018: if a future implementer thinks 'admin fallback would be easier', the Spec Kit explicitly rejects that — it IS the bug, not the workaround.

Tier

Trivial per ADR-0007 (prompt + spec docs, no runtime/schema/sacred-path mutation in this PR).

Implementation slices (Slice a/c = Lite; Slice b/d = Full + canary 3+3) land sequentially per 03-tasks.md.

Worktree note

This PR opened from claude/fork-A2-forgejo-mcp-identity-split branch in dedicated worktree /Users/pd/Developer/iskra-platform-2026-04-30-fork-A2/ per fork-dispatch-2026-05-18-retry-batch.md v0.1 isolation pattern. Zero shared-checkout collision risk (lesson from 2026-05-17).

Refs #56, PR #42 (STATE_OF_PLATFORM gap noted), PR #323 (Agent Access Plane sibling), fork-dispatch-2026-05-18 (PR #356)

## Summary Fork-A2 prebuild for issue #56 (operator Signal report 2026-05-04). Today's Forgejo MCP layer defaults to operator `pdurlej` admin identity for tool calls — even when active session is a cousin. Misattribution + admin token exposure surface too wide + reviewers can't tell which cousin performed an action. ## What's in **Spec Kit** (6 files in `docs/specs/forgejo-mcp-identity-split-v0/`): - `00-constitution.md` — 9 principles (P1-P9: one default identity per cousin, admin disabled by default, fail-closed on ambiguity, composes with Agent Access Plane, iskra deferred to v0.1) + non-goals + sacred boundary statements - `01-specify.md` — 9 machine-checkable acceptance criteria (A1-A9) + smoke contract - `02-plan.md` — 10 design decisions with alternatives compared (D1: thin router in platformctl; D2: PAT backing via Access Plane capability handle; D4: env-flag + typed confirmation for admin break-glass; D5: iskra deferral; D6: DeepSeek read-only-only) - `03-tasks.md` — 4 slices (a/b/c/d); ~1850 LOC; ~10-14h codex; tier per slice (Lite/Full) - `04-implement-notes.md` — 12 gotchas + prior art + composition notes - `README.md` — overview **Execution prompt** (`prompts/codex-forgejo-mcp-identity-split.md`): - Safety / production boundary section (per Codex 2026-05-17 feedback + PR #326 pattern) - Pre-flight identity check - Per-slice instructions with branch / tier / tasks / acceptance - ADR-0018 stop conditions (NO admin-fallback workarounds, NO accept-workaround outcomes) - Reporting format + cousin coordination rules ## Composes with - **PR #323 Agent Access Plane v0** — sibling; this v0's router consumes Access Plane session-scoped capability handles for per-cousin PAT delivery - ADR-0003 (Agent Access Plane), ADR-0005 (Coordination lanes), ADR-0010 (Cousin taxonomy), ADR-0017 (No stacked), ADR-0018 (Fix root causes) - PLATFORM_CHARTER §3 identity-isolation; AGENTS.md § Identity-isolation ## Key principles preserved (durable for context-compressed cousins) - **P2**: admin MCP `enabled_by_default: false` — explicit break-glass only (env flag + typed confirmation + audit log) - **P6**: fail-closed on identity ambiguity — NEVER fall back to admin - **P9**: iskra integration deferred to v0.1; sacred-path boundary respected; v0 publishes contract but does not modify iskra runtime Per ADR-0018: if a future implementer thinks 'admin fallback would be easier', the Spec Kit explicitly rejects that — it IS the bug, not the workaround. ## Tier Trivial per ADR-0007 (prompt + spec docs, no runtime/schema/sacred-path mutation in this PR). Implementation slices (Slice a/c = Lite; Slice b/d = Full + canary 3+3) land sequentially per `03-tasks.md`. ## Worktree note This PR opened from `claude/fork-A2-forgejo-mcp-identity-split` branch in dedicated worktree `/Users/pd/Developer/iskra-platform-2026-04-30-fork-A2/` per fork-dispatch-2026-05-18-retry-batch.md v0.1 isolation pattern. Zero shared-checkout collision risk (lesson from 2026-05-17). Refs #56, PR #42 (STATE_OF_PLATFORM gap noted), PR #323 (Agent Access Plane sibling), fork-dispatch-2026-05-18 (PR #356)

claude added 1 commit

2026-05-18 08:17:56 +02:00

docs(specs): prebuild for #56 Forgejo MCP identity split per agent v0

base-is-main / guard (pull_request) Successful in 1s

Details

canary-required / collect-diff (pull_request) Successful in 4s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 3s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 19s

Details

canary-required / canary (pull_request) Successful in 13s

Details

patchwarden-pr-sanity / sanity (pull_request) Successful in 20s

Details

5aa8994e4e

Closes operator Signal report 2026-05-04 + addresses identity-boundary
gap noted in PR #42 (STATE_OF_PLATFORM: Forgejo MCP still using operator
PAT). Today's MCP layer defaults to pdurlej admin identity for tool
calls even when active session is a cousin (claude/codex/glm/iskra/
hermes/DeepSeek). Per #56: misattribution, blurred accountability,
admin token exposure surface too wide.

Spec Kit (6 files) + companion execution prompt (1 file):
- 00-constitution.md  — 9 principles (P1-P9) + non-goals + sacred
- 01-specify.md       — 9 machine-checkable acceptance criteria
                        (A1-A9) + smoke contract for Slice (d)
- 02-plan.md          — 10 design decisions (D1-D10) with alternatives
                        compared; chosen: thin router in platformctl
                        composing with Agent Access Plane v0 (PR #323)
- 03-tasks.md         — 4 slices (a/b/c/d); ~1850 LOC; ~10-14h codex
- 04-implement-notes.md — gotchas, prior art, composition notes
- README.md           — overview + file index
- prompts/codex-forgejo-mcp-identity-split.md — execution prompt with
                        Safety/production boundary (per Codex 2026-05-17
                        feedback) + per-slice instructions + ADR-0018
                        stop conditions

Key Constitution principles:
- P1: cousin sees only own MCP identity by default
- P2: admin MCP disabled by default; explicit break-glass required
- P3: misattribution = P0 security finding, not UX issue
- P4: composes with Agent Access Plane v0 capability handles
- P6: fail closed on identity ambiguity (NEVER fall back to admin)
- P9: iskra integration deferred to v0.1 (sacred-path boundary respected)

Per ADR-0018: NO admin-fallback workarounds. NO "accept one cousin
failing" outcomes. NO silent admin reach widening.

Tier: Trivial per ADR-0007 (prompt + spec docs, no runtime/schema/
sacred-path mutation in this PR; implementation slices Lite/Full per
03-tasks.md).

Refs #56, PR #42, PR #323