✨ feat(contracts): add V2ContextAssignment for context.assign

[alain-sv]

Adds the typed contract for the new context.assign v2 action: Studio assigns a frozen selection of workspace/mission context items (ref + version + scope + title) to a job; the agent fetches content once via ContextClient and stores provenance (ref, version, hash, synced_at).

• V2ContextAssignmentItem + V2ContextAssignment in contracts.py (ContractModel, import-light)
• V2_ACTION_CONTEXT_ASSIGN = "context.assign" + exports
• Action table row in docs/2026_05_SUPERVAIZER_v2.md + CHANGELOG entry
• Additive only; dispatch rides the existing Server.v2_action machinery

Part of the Campaign Setup From Studio workstream (spec: RUNWAIZE docs/superpowers/specs/2026-07-02-campaign-setup-studio-integration-design.md). Companion to #65 (ContextClient) — both are needed for the next supervaizer release consumed by agent_interviewer.

🤖 Generated with Claude Code

[qodo-code-review]

PR Summary by Qodo

Add typed v2 contract for context.assign (V2ContextAssignment)

✨ Enhancement 📝 Documentation 🧪 Tests 🕐 20-40 Minutes

AI Description

• Introduces V2ContextAssignment / V2ContextAssignmentItem models for context.assign payloads.
• Exports V2_ACTION_CONTEXT_ASSIGN and new models at the package level.
• Documents the new action and adds parsing/empty-items coverage in contracts tests.

Diagram

graph TD
  A{{"Studio"}} --> B["context.assign action"] --> C["contracts.py"] --> D["package exports"]
  B --> E["v2 spec docs"]
  C --> F["contract tests"]
  C --> G["CHANGELOG"]
  subgraph Legend
    direction LR
    _ext{{"External"}} ~~~ _mod["Module/File"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep `context.assign` untyped (dict-only)

• ➕ No new public API surface area to maintain
• ➕ Maximally flexible if the payload shape is still evolving
• ➖ Downstream SDK users lose validation/autocomplete
• ➖ Harder to version/extend safely without breaking consumers

2. Stricter schema (Literal scope + datetime assigned_at)

• ➕ Earlier validation of malformed payloads (scope values, timestamp parsing)
• ➕ Clearer contract semantics for clients
• ➖ Higher risk of rejecting real-world payloads (timezone formats, future scope values)
• ➖ May conflict with current 'import-light' / interoperability goals

Recommendation: The PR’s approach (additive typed models + exported action id) is the right default for SDK ergonomics and forward-compatible versioning. If interop issues appear, consider tightening scope to a Literal[...] and assigned_at to a datetime in a later, explicitly versioned contract revision.

Files changed (5) +60 / -0

Enhancement (2) +26 / -0

__init__.pyRe-export 'V2_ACTION_CONTEXT_ASSIGN' and context assignment models +9/-0

Re-export 'V2_ACTION_CONTEXT_ASSIGN' and context assignment models

• Updates the lazy export map to include 'V2_ACTION_CONTEXT_ASSIGN', 'V2ContextAssignment', and 'V2ContextAssignmentItem'. Ensures SDK consumers can import these symbols directly from 'supervaizer'.

src/supervaizer/init.py

contracts.pyIntroduce 'V2ContextAssignment' / 'V2ContextAssignmentItem' contracts +17/-0

Introduce 'V2ContextAssignment' / 'V2ContextAssignmentItem' contracts

• Adds the 'V2_ACTION_CONTEXT_ASSIGN = "context.assign"' constant. Defines contract models representing a frozen selection of context items plus job/mission metadata and an ISO-8601 assignment timestamp.

src/supervaizer/contracts.py

Tests (1) +29 / -0

test_contracts.pyAdd tests for parsing and empty-items behavior of context assignment +29/-0

Add tests for parsing and empty-items behavior of context assignment

• Adds coverage that 'V2ContextAssignment' parses nested 'items' correctly and permits an explicit empty list. Also asserts the action id constant value is stable.

tests/test_contracts.py

Documentation (2) +5 / -0

2026_05_SUPERVAIZER_v2.mdDocument new 'context.assign' action in the v2 action table +1/-0

Document new 'context.assign' action in the v2 action table

• Adds a new row describing the 'context.assign' action semantics. Notes that the agent fetches content via 'ContextClient' and stores provenance fields.

docs/2026_05_SUPERVAIZER_v2.md

CHANGELOG.mdAdd Unreleased changelog entry for 'context.assign' contract +4/-0

Add Unreleased changelog entry for 'context.assign' contract

• Documents the newly added typed wire contract ('V2ContextAssignment', 'V2ContextAssignmentItem') and the exported action id constant. Clarifies the change is additive and uses existing dispatch machinery.

docs/CHANGELOG.md

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ac56ecc7ad

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 32 rules

1. Unvalidated context scope ✓ Resolved 🐞 Bug ≡ Correctness

Description

V2ContextAssignmentItem.scope is typed as a free-form str despite being documented as only
"workspace" or "mission", so invalid/typo values will validate and can propagate into downstream
logic. This also weakens the generated JSON schema compared to other v2 contract enums that are
constrained with Literal[...].

Code

src/supervaizer/contracts.py[R810-814]

+class V2ContextAssignmentItem(ContractModel):
+    ref: str  # Studio ContextItem ref, e.g. "supervaize.context.mission.january-brief"
+    version: int  # ContextItem version at selection time
+    scope: str  # "workspace" | "mission"
+    title: str

Relevance

⭐⭐⭐ High

Repo uses Literal for closed-set contract fields (e.g., JsonRpcRequest.jsonrpc in PR #47); schema
strictness valued.

PR-#47

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new contract comments indicate scope is intended to be a closed set, but it’s defined as str
so validation won’t reject unexpected values. Elsewhere in the same contracts module, similar
closed-vocabulary fields are modeled with Literal[...], demonstrating the established pattern for
enforcing protocol enums.

src/supervaizer/contracts.py[810-815]
src/supervaizer/contracts.py[867-869]
src/supervaizer/contracts.py[923-925]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`V2ContextAssignmentItem.scope` is currently declared as `str` while the comment indicates it should be a closed vocabulary ("workspace" | "mission"). This means Pydantic will accept any string and the JSON schema won’t communicate/validate the allowed values.

## Issue Context
The codebase already constrains protocol enums with `Literal[...]` (e.g., `V2ActionResult.status`, `V2JobSource.type`). Align `scope` with that pattern.

## Fix Focus Areas
- src/supervaizer/contracts.py[810-815]
- tests/test_contracts.py[738-761]

### Implementation notes
- Change `scope: str` to `scope: Literal["workspace", "mission"]` (or introduce a small `StrEnum` for scope if you expect reuse).
- Add a test asserting `ValidationError` on an invalid scope (e.g., "missions"), to prevent regressions.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5f0d8e126f

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 228d674bf3

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0a05820fa2

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".