ai-dev-workflow 0.2.0__tar.gz → 0.3.1__tar.gz

{ai_dev_workflow-0.2.0 → ai_dev_workflow-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-dev-workflow
-Version: 0.2.0
+Version: 0.3.1
 Summary: Provider-neutral AI-assisted development workflow and CLI
 Author: vuthethienlong
 Project-URL: Homepage, https://github.com/vuthethienlong/ai-dev-workflow
@@ -16,7 +16,7 @@ Requires-Dist: PyYAML>=6.0
 
 Reusable, provider-neutral workflow for AI-assisted software development.
 
-This repository starts from the workflow proven in the Dragon's Dogma 2 project and keeps Superpowers-style artifacts as first-class inputs: brainstorming, spec, ADR, implementation plan, tests, PR evidence and runtime verification.
+This repository provides a reusable, provider-neutral AI development workflow with first-class brainstorming, spec, ADR, implementation plan, tests, PR evidence and runtime verification artifacts.
 
 ## Default lifecycle
 
@@ -30,7 +30,7 @@ Brainstorm
   -> RED
   -> ImplementerAgent implements
   -> GREEN + regression
-  -> ReviewerAgent (optional/manual by default)
+  -> ReviewerAgent (automatic independent review by default)
   -> Integration
   -> Runtime verification batch when required
   -> Promotion / Done
@@ -41,7 +41,7 @@ Brainstorm
 - `ArchitectAgent`: brainstorm, spec, ADR and acceptance criteria.
 - `TesterAgent`: derives tests from the frozen contract and proves RED before implementation.
 - `ImplementerAgent`: implements without changing the frozen test contract; must reach GREEN and run applicable regression checks.
-- `ReviewerAgent`: optional semantic/architecture reviewer. Disabled/manual by default in v1.
+- `ReviewerAgent`: automatic semantic/architecture reviewer by default; must use a different worker_id from the Implementer. Separate credential/identity is optional.
 - `RuntimeVerifierAgent`: optional, project-specific runtime verification role.
 
 A role is not a model. GPT, Codex, Claude, local models or future providers are replaceable adapters under these contracts.
@@ -52,7 +52,7 @@ A role is not a model. GPT, Codex, Claude, local models or future providers are
 - `Ready` is the commitment/freeze boundary.
 - Test design happens before implementation.
 - Implementer may report a bad test/spec as blocked, but must not rewrite expectations merely to make tests pass.
-- Deterministic CI gates run before optional semantic AI review.
+- Deterministic CI gates run before automatic independent semantic review.
 - Runtime verification is separate from offline/CI verification.
 - Projects consume versioned reusable workflows such as `@v1`; they do not copy the engine.
 
@@ -70,6 +70,8 @@ project tests/runtime rules
 
 Its caller workflow will reference this repository's reusable workflow.
 
+The framework does **not** install its own CI/check workflow into consumer repositories, does not configure required status checks, and does not modify branch protection. Existing consumer-repository build, test, lint, security, approval, and merge policies remain authoritative. The generated `.github/workflows/ai-workflow.yml` is orchestration only.
+
 See:
 - `AGENTS.md`
 - `docs/lifecycle.md`
@@ -278,7 +280,7 @@ Local stdio MCP remains available with `--ado-mcp-mode local`. Supported MCP aut
 
 ## Worker registration
 
-Setup can register local, Codespaces, or cloud workers separately from AI provider configuration.
+Setup can register local, Codespaces, or cloud workers separately from AI provider configuration. Worker IDs are independent from credential identities, so multiple workers may share one credential reference.
 
 Example local hybrid worker:
 
@@ -326,14 +328,28 @@ Use `./bin/ai-workflow update --check` to inspect the configured framework ref,
 
 ## Install from PyPI
 
-Once a release is published to PyPI, consumers do not need to clone this repository:
+Consumers do not need to clone this repository:
 
 ```bash
 python -m pip install --upgrade ai-dev-workflow
-ai-workflow --help
+```
+
+After installation, start with the built-in guide:
+
+```bash
+ai-workflow guide
+```
+
+Typical first-run flow:
+
+```bash
+cd /path/to/project
 ai-workflow setup
+ai-workflow doctor
 ```
 
+The setup wizard detects the containing Git repository by default, shows the generated plan/configuration, and prints the next required steps after apply. Use `ai-workflow setup --help` for setup options and `ai-workflow guide` at any time for the end-to-end usage flow.
+
 The GitHub repository may remain private because normal consumers install the built distribution from PyPI rather than cloning the source repository.
 
 On another machine, install Python 3.10+ and run the same `pip install ai-dev-workflow` command. Project-specific configuration remains in each consumer repository.
@@ -346,3 +362,206 @@ ai-workflow update
 ```
 
 The first command upgrades the installed CLI package. The second migrates/updates the workflow installation in the current project.
+
+
+## PM and architecture planning
+
+Product planning and technical architecture are separate roles:
+
+```text
+Idea / chat
+→ PMAgent
+→ product Keep/Split/Merge proposal
+→ human approval
+→ ArchitectAgent
+→ technical Spec / ADR / decomposition
+→ approval for structural architecture changes
+→ Ready Freeze
+→ TesterAgent
+```
+
+PMAgent owns what/why: intent, value, scope, priority, product acceptance boundaries, Epic/Issue classification and product-level decomposition. ArchitectAgent owns how: technical boundaries, interfaces, data model, Spec/ADR, technical dependencies and execution decomposition.
+
+By default `workflow.planning.approval_policy` is `always`. Create, Split, Merge, Re-parent and Ready Freeze require explicit approval before provider mutation, and frozen contracts cannot be silently changed.
+
+## Active work and claims
+
+A selected task is not considered started until its worker/provider acknowledges it:
+
+```text
+ready/queued
+-> reserved
+-> offered
+-> accepted by worker/provider
+-> claim committed
+-> active status
+```
+
+Local agents acknowledge with the registered worker identity (for example through `ai-workflow claim`). Phase completion can be recorded with `ai-workflow complete-phase`, which releases the current claim and reserves an eligible worker for the next role. Automatic review always excludes the implementation worker_id; identity separation is enforced only when the optional strict-review policy is enabled.
+
+
+## Azure DevOps configuration boundary
+
+Azure DevOps project metadata and credentials are separate:
+
+- project configuration owns organization/project, logical Epic/Issue Work Item Type mappings, and Area/Iteration defaults;
+- worker configuration owns the Azure DevOps authentication strategy/credential reference;
+- setup may borrow a worker credential temporarily to discover project metadata, but never persists the raw token;
+- workers may share a credential reference when they intentionally act as the same ADO identity.
+
+Area Path and Iteration Path options are discovered from the project's existing Azure DevOps classification nodes. Setup selects from existing values; it does not create or modify the project's classification hierarchy.
+
+## Worker credentials and identity
+
+Worker IDs and credentials are separate concepts. Several workers may intentionally use the same credential reference and therefore operate as the same GitHub/ADO actor. This is valid for normal planning, testing, implementation, and runtime work.
+
+The workflow verifies effective actor identity where possible. A distinct credential is not required merely because workers are different. By default, ReviewerAgent only needs a different worker_id from the Implementer. Projects that require stronger separation may enable `reviewer.require_distinct_identity: true`.
+
+
+## Local parallel workers
+
+One local machine may register multiple workers that intentionally share the same GitHub/Azure DevOps credential sessions while using isolated working folders.
+
+Example:
+
+```yaml
+workers:
+  - worker_id: codex-01
+    environment: local
+    provider: codex
+    workspace:
+      strategy: git-worktree
+      root: G:\ai-workers\codex-01
+
+  - worker_id: ccr-01
+    environment: local
+    provider: ccr
+    workspace:
+      strategy: git-worktree
+      root: G:\ai-workers\ccr-01
+```
+
+Add another local worker after initial setup:
+
+```powershell
+ai-workflow add-worker
+```
+
+or non-interactively:
+
+```powershell
+ai-workflow add-worker `
+  --worker-id codex-02 `
+  --provider codex `
+  --mode hybrid `
+  --workspace G:\ai-workers\codex-02 `
+  --workspace-strategy git-worktree
+```
+
+By default the new local worker inherits credential references from an existing local worker. It still receives its own `worker_id` and isolated workspace. Use `--no-inherit-credentials` when the worker must use a different identity.
+
+At runtime, a local worker is resolved in this order:
+
+1. explicit `--worker <id>`;
+2. `AI_WORKFLOW_WORKER_ID`;
+3. current working directory contained by one configured `workspace.root`.
+
+This makes it possible to open separate terminals in separate worker folders and run tasks concurrently without repeating the worker ID.
+
+## Claude Code Router local provider
+
+Claude Code Router can be registered as a local provider:
+
+```yaml
+providers:
+  ccr:
+    type: claude-code-router
+    base_url: http://127.0.0.1:3456
+    auth:
+      type: none
+```
+
+The gateway defaults to `http://127.0.0.1:3456`. A client-key environment reference can be configured when the local router is protected. Claude Code Router uses the same `CLAUDE.md` instruction adapter as Claude Code, while `AGENTS.md` remains the shared workflow instruction source.
+
+A local CCR worker can then be registered with its own workspace:
+
+```powershell
+ai-workflow add-worker `
+  --worker-id ccr-01 `
+  --provider ccr `
+  --workspace G:\ai-workers\ccr-01
+```
+
+
+### Step-by-step add-worker wizard
+
+Running `ai-workflow add-worker` with no `--non-interactive` flag now opens a structured wizard:
+
+1. review existing project/provider configuration;
+2. choose a worker id;
+3. choose planner/executor/hybrid mode;
+4. choose an existing AI provider;
+5. choose roles;
+6. choose the local workspace folder;
+7. choose `git-worktree` or `folder` workspace strategy;
+8. choose whether to inherit an existing local worker's credential references or configure separate GitHub/ADO references;
+9. choose skills and capacity;
+10. review the final worker configuration and confirm before saving.
+
+The wizard never stores raw tokens. It only stores credential strategies/references already supported by the worker identity model.
+
+For scripting/automation, keep the deterministic flag-based flow:
+
+```powershell
+ai-workflow add-worker `
+  --non-interactive `
+  --worker-id codex-02 `
+  --provider codex `
+  --mode hybrid `
+  --roles "ArchitectAgent|TesterAgent|ImplementerAgent|ReviewerAgent" `
+  --workspace G:\ai-workers\codex-02 `
+  --workspace-strategy git-worktree
+```
+
+Use `--no-inherit-credentials` when the new worker must not reuse an existing local worker's credential references.
+
+
+## Consumer worker registry and live presence
+
+When a GitHub Issues or composite project has execution workers, setup writes:
+
+```text
+.github/ai-workflow-worker-registry.json
+```
+
+This committed registry contains routing metadata only:
+
+- worker id;
+- execution location;
+- provider id;
+- roles/capabilities;
+- capacity;
+- managed/unmanaged flag;
+- GitHub assignee when required.
+
+It intentionally excludes machine-local paths, machine ids, client launch commands, credential references, tokens, identities, heartbeat data, and active sessions.
+
+For local execution workers, setup also creates or reuses one closed coordination Issue marked with:
+
+```text
+<!-- ai-dev-workflow:worker-presence -->
+```
+
+The Issue number is stored as project-level dispatcher metadata. Local workers publish the existing queue-dispatcher presence-v2 contract to that Issue using their own verified GitHub identity.
+
+`ai-workflow worker open <worker-id>` keeps the local and central heartbeat alive while the configured Codex/Claude Code client process is running. When the client exits, the worker is reported offline.
+
+For headless or daemon-style workers:
+
+```powershell
+ai-workflow worker serve <worker-id>
+```
+
+A worker keeps one presence comment and updates it on each heartbeat; it does not append a new comment every interval. The central dispatcher reads the consumer registry plus live presence before reserving work.
+
+The consumer orchestration workflow remains `.github/workflows/ai-workflow.yml`. This integration does not install framework CI/check workflows, does not configure required status checks, and does not modify branch protection.

{ai_dev_workflow-0.2.0 → ai_dev_workflow-0.3.1}/README.md

@@ -2,7 +2,7 @@
 
 Reusable, provider-neutral workflow for AI-assisted software development.
 
-This repository starts from the workflow proven in the Dragon's Dogma 2 project and keeps Superpowers-style artifacts as first-class inputs: brainstorming, spec, ADR, implementation plan, tests, PR evidence and runtime verification.
+This repository provides a reusable, provider-neutral AI development workflow with first-class brainstorming, spec, ADR, implementation plan, tests, PR evidence and runtime verification artifacts.
 
 ## Default lifecycle
 
@@ -16,7 +16,7 @@ Brainstorm
   -> RED
   -> ImplementerAgent implements
   -> GREEN + regression
-  -> ReviewerAgent (optional/manual by default)
+  -> ReviewerAgent (automatic independent review by default)
   -> Integration
   -> Runtime verification batch when required
   -> Promotion / Done
@@ -27,7 +27,7 @@ Brainstorm
 - `ArchitectAgent`: brainstorm, spec, ADR and acceptance criteria.
 - `TesterAgent`: derives tests from the frozen contract and proves RED before implementation.
 - `ImplementerAgent`: implements without changing the frozen test contract; must reach GREEN and run applicable regression checks.
-- `ReviewerAgent`: optional semantic/architecture reviewer. Disabled/manual by default in v1.
+- `ReviewerAgent`: automatic semantic/architecture reviewer by default; must use a different worker_id from the Implementer. Separate credential/identity is optional.
 - `RuntimeVerifierAgent`: optional, project-specific runtime verification role.
 
 A role is not a model. GPT, Codex, Claude, local models or future providers are replaceable adapters under these contracts.
@@ -38,7 +38,7 @@ A role is not a model. GPT, Codex, Claude, local models or future providers are
 - `Ready` is the commitment/freeze boundary.
 - Test design happens before implementation.
 - Implementer may report a bad test/spec as blocked, but must not rewrite expectations merely to make tests pass.
-- Deterministic CI gates run before optional semantic AI review.
+- Deterministic CI gates run before automatic independent semantic review.
 - Runtime verification is separate from offline/CI verification.
 - Projects consume versioned reusable workflows such as `@v1`; they do not copy the engine.
 
@@ -56,6 +56,8 @@ project tests/runtime rules
 
 Its caller workflow will reference this repository's reusable workflow.
 
+The framework does **not** install its own CI/check workflow into consumer repositories, does not configure required status checks, and does not modify branch protection. Existing consumer-repository build, test, lint, security, approval, and merge policies remain authoritative. The generated `.github/workflows/ai-workflow.yml` is orchestration only.
+
 See:
 - `AGENTS.md`
 - `docs/lifecycle.md`
@@ -264,7 +266,7 @@ Local stdio MCP remains available with `--ado-mcp-mode local`. Supported MCP aut
 
 ## Worker registration
 
-Setup can register local, Codespaces, or cloud workers separately from AI provider configuration.
+Setup can register local, Codespaces, or cloud workers separately from AI provider configuration. Worker IDs are independent from credential identities, so multiple workers may share one credential reference.
 
 Example local hybrid worker:
 
@@ -312,14 +314,28 @@ Use `./bin/ai-workflow update --check` to inspect the configured framework ref,
 
 ## Install from PyPI
 
-Once a release is published to PyPI, consumers do not need to clone this repository:
+Consumers do not need to clone this repository:
 
 ```bash
 python -m pip install --upgrade ai-dev-workflow
-ai-workflow --help
+```
+
+After installation, start with the built-in guide:
+
+```bash
+ai-workflow guide
+```
+
+Typical first-run flow:
+
+```bash
+cd /path/to/project
 ai-workflow setup
+ai-workflow doctor
 ```
 
+The setup wizard detects the containing Git repository by default, shows the generated plan/configuration, and prints the next required steps after apply. Use `ai-workflow setup --help` for setup options and `ai-workflow guide` at any time for the end-to-end usage flow.
+
 The GitHub repository may remain private because normal consumers install the built distribution from PyPI rather than cloning the source repository.
 
 On another machine, install Python 3.10+ and run the same `pip install ai-dev-workflow` command. Project-specific configuration remains in each consumer repository.
@@ -332,3 +348,206 @@ ai-workflow update
 ```
 
 The first command upgrades the installed CLI package. The second migrates/updates the workflow installation in the current project.
+
+
+## PM and architecture planning
+
+Product planning and technical architecture are separate roles:
+
+```text
+Idea / chat
+→ PMAgent
+→ product Keep/Split/Merge proposal
+→ human approval
+→ ArchitectAgent
+→ technical Spec / ADR / decomposition
+→ approval for structural architecture changes
+→ Ready Freeze
+→ TesterAgent
+```
+
+PMAgent owns what/why: intent, value, scope, priority, product acceptance boundaries, Epic/Issue classification and product-level decomposition. ArchitectAgent owns how: technical boundaries, interfaces, data model, Spec/ADR, technical dependencies and execution decomposition.
+
+By default `workflow.planning.approval_policy` is `always`. Create, Split, Merge, Re-parent and Ready Freeze require explicit approval before provider mutation, and frozen contracts cannot be silently changed.
+
+## Active work and claims
+
+A selected task is not considered started until its worker/provider acknowledges it:
+
+```text
+ready/queued
+-> reserved
+-> offered
+-> accepted by worker/provider
+-> claim committed
+-> active status
+```
+
+Local agents acknowledge with the registered worker identity (for example through `ai-workflow claim`). Phase completion can be recorded with `ai-workflow complete-phase`, which releases the current claim and reserves an eligible worker for the next role. Automatic review always excludes the implementation worker_id; identity separation is enforced only when the optional strict-review policy is enabled.
+
+
+## Azure DevOps configuration boundary
+
+Azure DevOps project metadata and credentials are separate:
+
+- project configuration owns organization/project, logical Epic/Issue Work Item Type mappings, and Area/Iteration defaults;
+- worker configuration owns the Azure DevOps authentication strategy/credential reference;
+- setup may borrow a worker credential temporarily to discover project metadata, but never persists the raw token;
+- workers may share a credential reference when they intentionally act as the same ADO identity.
+
+Area Path and Iteration Path options are discovered from the project's existing Azure DevOps classification nodes. Setup selects from existing values; it does not create or modify the project's classification hierarchy.
+
+## Worker credentials and identity
+
+Worker IDs and credentials are separate concepts. Several workers may intentionally use the same credential reference and therefore operate as the same GitHub/ADO actor. This is valid for normal planning, testing, implementation, and runtime work.
+
+The workflow verifies effective actor identity where possible. A distinct credential is not required merely because workers are different. By default, ReviewerAgent only needs a different worker_id from the Implementer. Projects that require stronger separation may enable `reviewer.require_distinct_identity: true`.
+
+
+## Local parallel workers
+
+One local machine may register multiple workers that intentionally share the same GitHub/Azure DevOps credential sessions while using isolated working folders.
+
+Example:
+
+```yaml
+workers:
+  - worker_id: codex-01
+    environment: local
+    provider: codex
+    workspace:
+      strategy: git-worktree
+      root: G:\ai-workers\codex-01
+
+  - worker_id: ccr-01
+    environment: local
+    provider: ccr
+    workspace:
+      strategy: git-worktree
+      root: G:\ai-workers\ccr-01
+```
+
+Add another local worker after initial setup:
+
+```powershell
+ai-workflow add-worker
+```
+
+or non-interactively:
+
+```powershell
+ai-workflow add-worker `
+  --worker-id codex-02 `
+  --provider codex `
+  --mode hybrid `
+  --workspace G:\ai-workers\codex-02 `
+  --workspace-strategy git-worktree
+```
+
+By default the new local worker inherits credential references from an existing local worker. It still receives its own `worker_id` and isolated workspace. Use `--no-inherit-credentials` when the worker must use a different identity.
+
+At runtime, a local worker is resolved in this order:
+
+1. explicit `--worker <id>`;
+2. `AI_WORKFLOW_WORKER_ID`;
+3. current working directory contained by one configured `workspace.root`.
+
+This makes it possible to open separate terminals in separate worker folders and run tasks concurrently without repeating the worker ID.
+
+## Claude Code Router local provider
+
+Claude Code Router can be registered as a local provider:
+
+```yaml
+providers:
+  ccr:
+    type: claude-code-router
+    base_url: http://127.0.0.1:3456
+    auth:
+      type: none
+```
+
+The gateway defaults to `http://127.0.0.1:3456`. A client-key environment reference can be configured when the local router is protected. Claude Code Router uses the same `CLAUDE.md` instruction adapter as Claude Code, while `AGENTS.md` remains the shared workflow instruction source.
+
+A local CCR worker can then be registered with its own workspace:
+
+```powershell
+ai-workflow add-worker `
+  --worker-id ccr-01 `
+  --provider ccr `
+  --workspace G:\ai-workers\ccr-01
+```
+
+
+### Step-by-step add-worker wizard
+
+Running `ai-workflow add-worker` with no `--non-interactive` flag now opens a structured wizard:
+
+1. review existing project/provider configuration;
+2. choose a worker id;
+3. choose planner/executor/hybrid mode;
+4. choose an existing AI provider;
+5. choose roles;
+6. choose the local workspace folder;
+7. choose `git-worktree` or `folder` workspace strategy;
+8. choose whether to inherit an existing local worker's credential references or configure separate GitHub/ADO references;
+9. choose skills and capacity;
+10. review the final worker configuration and confirm before saving.
+
+The wizard never stores raw tokens. It only stores credential strategies/references already supported by the worker identity model.
+
+For scripting/automation, keep the deterministic flag-based flow:
+
+```powershell
+ai-workflow add-worker `
+  --non-interactive `
+  --worker-id codex-02 `
+  --provider codex `
+  --mode hybrid `
+  --roles "ArchitectAgent|TesterAgent|ImplementerAgent|ReviewerAgent" `
+  --workspace G:\ai-workers\codex-02 `
+  --workspace-strategy git-worktree
+```
+
+Use `--no-inherit-credentials` when the new worker must not reuse an existing local worker's credential references.
+
+
+## Consumer worker registry and live presence
+
+When a GitHub Issues or composite project has execution workers, setup writes:
+
+```text
+.github/ai-workflow-worker-registry.json
+```
+
+This committed registry contains routing metadata only:
+
+- worker id;
+- execution location;
+- provider id;
+- roles/capabilities;
+- capacity;
+- managed/unmanaged flag;
+- GitHub assignee when required.
+
+It intentionally excludes machine-local paths, machine ids, client launch commands, credential references, tokens, identities, heartbeat data, and active sessions.
+
+For local execution workers, setup also creates or reuses one closed coordination Issue marked with:
+
+```text
+<!-- ai-dev-workflow:worker-presence -->
+```
+
+The Issue number is stored as project-level dispatcher metadata. Local workers publish the existing queue-dispatcher presence-v2 contract to that Issue using their own verified GitHub identity.
+
+`ai-workflow worker open <worker-id>` keeps the local and central heartbeat alive while the configured Codex/Claude Code client process is running. When the client exits, the worker is reported offline.
+
+For headless or daemon-style workers:
+
+```powershell
+ai-workflow worker serve <worker-id>
+```
+
+A worker keeps one presence comment and updates it on each heartbeat; it does not append a new comment every interval. The central dispatcher reads the consumer registry plus live presence before reserving work.
+
+The consumer orchestration workflow remains `.github/workflows/ai-workflow.yml`. This integration does not install framework CI/check workflows, does not configure required status checks, and does not modify branch protection.

{ai_dev_workflow-0.2.0 → ai_dev_workflow-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-dev-workflow"
-version = "0.2.0"
+version = "0.3.1"
 description = "Provider-neutral AI-assisted development workflow and CLI"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -31,6 +31,10 @@ ai-workflow = "ai_workflow_cli:main"
 package-dir = {"" = "tools"}
 py-modules = [
   "ado_mcp",
+  "workflow_handoff",
+  "workflow_runtime",
+  "work_claim",
+  "active_work_context",
   "ado_provider",
   "ai_provider",
   "ai_workflow_cli",
@@ -39,11 +43,18 @@ py-modules = [
   "github_work_item_provider",
   "instruction_adapter",
   "issue_publisher",
+  "planning_approval",
   "planning_context",
   "setup_context",
   "setup_wizard",
   "source_connection",
+  "skill_registry",
+  "work_breakdown",
   "work_item_provider",
   "work_item_registry",
+  "worker_identity",
+  "worker_presence",
   "worker_registry",
+  "worker_runtime_manager",
+  "worker_session",
 ]

ai_dev_workflow-0.3.1/tests/test_active_work_context.py

@@ -0,0 +1,48 @@
+import sys, unittest
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "tools"))
+
+from active_work_context import (
+    build_active_work_context, validate_context, role_for_phase,
+    queued_status_for_phase, active_status_for_phase,
+)
+
+
+class Tests(unittest.TestCase):
+    def test_context_binds_worker_issue_phase_and_role(self):
+        worker={
+            "worker_id":"local-1","provider":"chatgpt","environment":"local",
+            "roles":["TesterAgent","ImplementerAgent"],
+            "identity":{"github":{"actor":"devuser"}},
+        }
+        ctx=build_active_work_context(
+            worker=worker,
+            phase="test-design",
+            github_issue={"repository":"o/r","number":85,"url":"https://example/85"},
+            ado_work_item={"id":1234},
+            epic={"id":1200},
+            session_id="session-1",
+            claim={"state":"reserved","dispatch_id":"d1"},
+        )
+        self.assertEqual(ctx["required_role"],"TesterAgent")
+        self.assertEqual(ctx["queued_status"],"ready")
+        self.assertEqual(ctx["active_status"],"in-progress")
+        self.assertEqual(ctx["ado_work_item"]["id"],1234)
+        self.assertEqual(validate_context(ctx),[])
+
+    def test_worker_must_support_phase_role(self):
+        with self.assertRaisesRegex(ValueError,"does not support"):
+            build_active_work_context(
+                worker={"worker_id":"w","roles":["ImplementerAgent"]},
+                phase="code-review",
+                github_issue={"repository":"o/r","number":1},
+            )
+
+    def test_phase_maps(self):
+        self.assertEqual(role_for_phase("implementing"),"ImplementerAgent")
+        self.assertEqual(queued_status_for_phase("code-review"),"in-review")
+        self.assertEqual(active_status_for_phase("runtime-verify"),"runtime-pending")
+        self.assertIsNone(role_for_phase("done"))
+
+
+if __name__=="__main__": unittest.main()