spec(security): add security boundary specification and refactor model spec

BOOKMARKS.md

@@ -25,10 +25,11 @@ Desired state of the system, organized by capability domain.
 
 | Spec | Domain | Purpose |
 |------|--------|---------|
-| [Ambient Data Model](specs/sessions/ambient-model.spec.md) | sessions | Platform-wide data model: projects, agents, sessions, credentials, RBAC |
+| [Ambient Data Model](specs/api/ambient-model.spec.md) | api | Platform-wide data model: projects, agents, sessions, credentials, RBAC |
 | [Control Plane](specs/control-plane/control-plane.spec.md) | control-plane | CP architecture, runner structure, K8s provisioning |
 | [Runner](specs/agents/runner.spec.md) | agents | Runner subprocess lifecycle, bridges, gRPC/HTTP endpoints |
 | [MCP Server](specs/integrations/mcp-server.spec.md) | integrations | MCP tool definitions, sidecar and public endpoint modes |
+| [Security](specs/security/security.spec.md) | security | Identity boundaries, credential authorization, per-session isolation, design decisions |
 
 Feature specs remain in numbered directories under `specs/` (e.g., `specs/001-*/spec.md`).
 

docs/internal/design/README.md

@@ -52,6 +52,7 @@ A spec is **complete** when it is unambiguous enough that two engineers reading
 | `ambient-model.spec.md` | All platform Kinds: Session, Agent, Project, Inbox, Role, RoleBinding, User |
 | `control-plane.spec.md` | Control plane gRPC protocol, session fan-out, runner contract |
 | `mcp-server.spec.md` | MCP server tools, annotation state, sidecar transport |
+| `security.spec.md` | Identity boundaries, credential authorization, per-session SA isolation |
 
 ### Guide files (`*.guide.md`)
 
@@ -65,7 +66,7 @@ Guides are **living documents**. Every time the workflow runs and something is d
 
 | Guide | Paired spec |
 |---|---|
-| `workflows/sessions/ambient-model.workflow.md` | `specs/sessions/ambient-model.spec.md` |
+| `workflows/sessions/ambient-model.workflow.md` | `specs/api/ambient-model.spec.md` |
 | `workflows/control-plane/control-plane.workflow.md` | `specs/control-plane/control-plane.spec.md` |
 | `workflows/integrations/mcp-server.workflow.md` | `specs/integrations/mcp-server.spec.md` |
 
@@ -133,6 +134,6 @@ Every time the loop stops because something was wrong, the documents get better.
 ## Reading Order for a New Contributor
 
 1. This README — the why
-2. `specs/sessions/ambient-model.spec.md` — what the platform is
+2. `specs/api/ambient-model.spec.md` — what the platform is
 3. `workflows/sessions/ambient-model.workflow.md` — how changes are made
 4. The context file for the component you are working on

skills/devflow/SKILL.md

@@ -78,7 +78,7 @@ Every component has a spec file. Load the spec for the component being changed:
 
 | Component | Spec | Guide |
 |-----------|------|-------|
-| Data Model / API / CLI / RBAC | `specs/sessions/ambient-model.spec.md` | `workflows/sessions/ambient-model.workflow.md` |
+| Data Model / API / CLI / RBAC | `specs/api/ambient-model.spec.md` | `workflows/sessions/ambient-model.workflow.md` |
 
 ### 2b. Modify the Spec
 
@@ -354,7 +354,7 @@ But prefer fixing the lint/format issue instead.
 | `specs/standards/backend/conventions.spec.md` | SDK generation |
 | `specs/standards/control-plane/conventions.spec.md` | CP fan-out, runner contract |
 | `specs/standards/frontend/conventions.spec.md` | Frontend build, React Query |
-| `specs/sessions/ambient-model.spec.md` | Data model spec (source of truth) |
+| `specs/api/ambient-model.spec.md` | Data model spec (source of truth) |
 | `workflows/sessions/ambient-model.workflow.md` | Implementation workflow (wave-based) |
 
 ---

specs/index.spec.md

@@ -79,9 +79,11 @@ specs/
 
 | Domain | Covers |
 |--------|--------|
-| `sessions/` | Lifecycle, initialization, status, messages, events, data model |
+| `api/` | Platform data model: projects, agents, sessions, credentials, RBAC, CLI |
+| `sessions/` | Lifecycle, initialization, status, messages, events |
 | `agents/` | Agent model, runtime registry, prompts, runners |
 | `control-plane/` | Reconciliation, operator, scheduling |
 | `frontend/` | UI rendering, session views, markdown, navigation |
 | `integrations/` | MCP, Gerrit, external services |
+| `security/` | Identity boundaries, credential authorization, per-session isolation |
 | `standards/` | Cross-cutting engineering constraints by component |

workflows/integrations/mcp-server.workflow.md

@@ -461,5 +461,5 @@ Lessons learned:
 - Full per-tool schemas, return shapes, and error tables: `specs/integrations/mcp-server.spec.md`
 - Annotation key conventions and fleet state protocol: `docs/internal/proposals/agent-fleet-state-schema.md`
 - Agent visual language (how purple SEND/WAIT blocks map to MCP tools): `docs/internal/proposals/agent-script-visual-language.md`
-- Platform data model: `specs/sessions/ambient-model.spec.md`
+- Platform data model: `specs/api/ambient-model.spec.md`
 - Component pipeline and wave pattern: `workflows/sessions/ambient-model.workflow.md`

workflows/sessions/ambient-model.workflow.md

@@ -64,7 +64,7 @@ Checklist:
 
 ### Step 2 — Read the Spec
 
-Read `specs/sessions/ambient-model.spec.md` in full.
+Read `specs/api/ambient-model.spec.md` in full.
 
 Extract and hold in working memory:
 
@@ -453,7 +453,7 @@ The old Gin/K8s backend (`components/backend/`) is covered by `.claude/context/b
 
 | Artifact              | Location                                             | Owner             |
 | --------------------- | ---------------------------------------------------- | ----------------- |
-| Spec                  | `specs/sessions/ambient-model.spec.md`               | Human / consensus |
+| Spec                  | `specs/api/ambient-model.spec.md`               | Human / consensus |
 | This workflow         | `workflows/sessions/ambient-model.workflow.md` | Updated each run  |
 | OpenAPI spec          | `components/ambient-api-server/openapi/openapi.yaml` | API wave          |
 | Generated SDK         | `components/ambient-sdk/go-sdk/`                     | SDK wave          |