From b769b70c07d22f7a802f6d4219201e7bbd2a3ab0 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 6 Jul 2026 12:32:32 +0100 Subject: [PATCH 1/4] Plan actor identity profile registry --- .agent-loop/LOOP_STATE.md | 41 +- .agent-loop/REVIEW_LOG.md | 65 +++ .agent-loop/WORK_QUEUE.md | 13 +- .../CHUNK_MAP.md | 139 ++++++ .../STATUS.md | 17 +- ...-001-11-actor-identity-profile-registry.md | 448 ++++++++++++++++++ docs/architecture_data_model.md | 104 ++-- docs/architecture_system_architecture.md | 15 +- docs/glossary.md | 28 ++ docs/operations_roles_permissions.md | 29 +- docs/spec_chunk_4_task_queue_assignment.md | 5 + 11 files changed, 830 insertions(+), 74 deletions(-) create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-11-actor-identity-profile-registry.md diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index 3cd9686..af4f40a 100644 --- a/.agent-loop/LOOP_STATE.md +++ b/.agent-loop/LOOP_STATE.md @@ -3,17 +3,18 @@ ## Current State - Active initiative: `WS-POL-001` - Submission Artifact Policy Foundation -- Active planning chunk: none -- Active implementation chunk: `WS-POL-001-10` - Pre-Submit Live Drill Hardening -- Branch: `codex/ws-pol-001-10-pre-submit-hardening` -- Status: `WS-POL-001-10` is open as PR #72. Implementation and internal - review are complete; CodeRabbit follow-up fixes are addressed locally and the - branch is awaiting pushed CI reruns and the human merge checkpoint. -- Last merged implementation SHA: `8a524de` -- Last merge commit: `8a524de` -- Current gate: PR #72 external checks after evidence rebind, then human merge - decision -- Next chunk: inactive until `WS-POL-001-10` reaches a human checkpoint +- Active planning chunk: `WS-POL-001-11` - Actor Identity And Profile Registry +- Active implementation chunk: none +- Branch: `codex/ws-pol-001-11-actor-identity-profile-contract` +- Status: `WS-POL-001-10` merged through PR #72. `WS-POL-001-11` is in active + planning/spec contract review for Workstream's local actor identity and + profile registry. Implementation is inactive until human review approves the + contract. +- Last merged implementation SHA: `cc78f2a` +- Last merge commit: `1bbde47` +- Current gate: `WS-POL-001-11` contract review +- Next chunk: `WS-POL-001-11` is contract-only until human review approves the + implementation boundary ## Operating Rule @@ -41,12 +42,12 @@ project setup runtime boundary. It removed the production fixture adapter and did not change task, checker, post-submit, review, revision, payment, reputation, blockchain, frontend, or object-storage behavior. -The active `WS-POL-001-10` chunk is a corrective hardening chunk for the -pre-submit live API drill. It fixes guide-version conflict mapping, guide-create -source snapshot capture, active-guide checker summary visibility, worker -self-profile onboarding, and failed pre-submit audit evidence. It does not -change post-submit policy, review, revision, payment, reputation, blockchain, -frontend, or agent-runtime behavior. +The merged `WS-POL-001-10` chunk was a corrective hardening chunk for the +pre-submit live API drill. It fixed guide-version conflict mapping, +guide-create source snapshot capture, active-guide checker summary visibility, +worker self-profile onboarding, and failed pre-submit audit evidence. It did +not change post-submit policy, review, revision, payment, reputation, +blockchain, frontend, or agent-runtime behavior. ## Last Review State @@ -107,5 +108,7 @@ frontend, or agent-runtime behavior. - PR #71 merged into `main` as `8a524de`. - `WS-POL-001-10` started after the user's explicit start signal for the first five pre-submit hardening fixes from the live API drill. -- PR #72 is open from `codex/ws-pol-001-10-pre-submit-hardening`; CodeRabbit - follow-up fixes are applied locally and require CI rerun after push. +- PR #72 merged into `main` as `1bbde47`. +- `WS-POL-001-11` is the next planned bounded chunk. It should add local + Workstream actor identity and actor profile registries for verified Flow + actors before the next Terminal Benchmark live API drill. diff --git a/.agent-loop/REVIEW_LOG.md b/.agent-loop/REVIEW_LOG.md index de3bc4e..e0f5685 100644 --- a/.agent-loop/REVIEW_LOG.md +++ b/.agent-loop/REVIEW_LOG.md @@ -228,3 +228,68 @@ and removal of remaining construction-state compatibility surfaces. Evidence: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-08-internal-review-evidence.md` External review response: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-08-external-review-response.md` + +## WS-POL-001-09 + +Status: merged through PR #71 on 2026-07-06. + +Merge commit: `8a524de` + +Required reviewer tracks: + +- senior engineering +- QA/test +- security/auth +- product/ops +- architecture +- CI integrity +- docs +- reuse/dedup +- test delta + +Result: PASS after fixes; external review addressed; GitHub checks passed. + +Scope: removed the production `local_fixture` project setup runtime and old +runtime selector, kept deterministic test behavior in explicit test-local +fakes only, and preserved OpenAI Agents SDK as the configured project setup +runtime boundary. + +Evidence: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-09-internal-review-evidence.md` + +External review response: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-09-external-review-response.md` + +## WS-POL-001-10 + +Status: merged through PR #72 on 2026-07-06. + +Merge commit: `1bbde47` + +Reviewed implementation SHA: `cc78f2a` + +Required reviewer tracks: + +- senior engineering +- QA/test +- security/auth +- product/ops +- architecture +- CI integrity +- docs +- reuse/dedup +- test delta + +Result: PASS after fixes; external review addressed; GitHub checks passed. + +Scope: duplicate guide-version conflict handling, guide-create source snapshot +capture, active-guide checker summary visibility, worker self-profile +onboarding through authenticated API, nullable worker identity response +coverage, and durable failed-pre-submit audit evidence without creating a +submission. + +Next chunk: `WS-POL-001-11` should define and then implement local actor +identity and actor profile registries before the next Terminal Benchmark live +API drill. + +Evidence: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-10-internal-review-evidence.md` + +External review response: `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-10-external-review-response.md` diff --git a/.agent-loop/WORK_QUEUE.md b/.agent-loop/WORK_QUEUE.md index 92a1cfa..91b577f 100644 --- a/.agent-loop/WORK_QUEUE.md +++ b/.agent-loop/WORK_QUEUE.md @@ -4,7 +4,7 @@ | Chunk | Title | Risk | Status | |---|---|---:|---| -| TBD | Next WS-POL-001 bounded chunk | L1 | Inactive until explicit user start signal and chunk contract | +| `WS-POL-001-11` | Actor Identity And Profile Registry Contract | L1 | Contract-only branch active; implementation waits for human review | ## Completed @@ -21,13 +21,16 @@ | `WS-POL-001-06` | Terminal Benchmark Real Fixture Drill | L1 | Merged through PR #67 | | `WS-POL-001-07` | Task Contract Artifact Field Cleanup | L1 | Merged through PR #68 | | `WS-POL-001-08` | Celery Project Setup Pipeline | L1 | Merged through PR #69 | +| `WS-POL-001-09` | OpenAI Agents SDK Runtime Only | L1 | Merged through PR #71 | +| `WS-POL-001-10` | Pre-Submit Live Drill Hardening | L1 | Merged through PR #72 | ## Proposed Next -No chunk is active. The next likely step is a new bounded chunk to prove the -automatic Celery project setup path against the Terminal Benchmark example with -real API calls, but it must receive an explicit chunk contract before -implementation starts. +The next implementation chunk should create local Workstream actor identity and +actor profile registries for verified Flow actors. It must not turn Workstream +into the auth provider, and persisted profiles must not become permission +authority. After that merge, rerun the Terminal Benchmark live API drill through +real HTTP calls. ## Blocked diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md index 5d9ff4c..82a7fad 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md @@ -749,3 +749,142 @@ The removed fixture path cannot be used as a production project setup runtime; test fakes stay visibly test-local; operator docs do not imply fallback behavior; and the project-agent port remains available for deliberate future runtime providers. + +### WS-POL-001-10: Pre-Submit Live Drill Hardening + +Goal: + +Harden the concrete pre-submit setup and intake gaps found during the real +Terminal Benchmark API drill. + +Risk: + +L1 + +Depends on: + +`WS-POL-001-09` + +Status: + +Merged through PR #72. + +Scope: + +Duplicate guide-version conflict mapping, guide-create source snapshot capture, +active-guide checker summary visibility, worker self-profile onboarding through +authenticated API, and durable failed-pre-submit audit evidence without creating +a submission. + +Human review focus: + +Worker profile setup is a real authenticated API path, active-guide checker +visibility does not expose compiled bundle bodies, and failed pre-submit +attempts remain outside product review decisions. + +### WS-POL-001-11: Actor Identity And Profile Registry + +Goal: + +Create local `ActorIdentity` and shared `ActorProfile` registries for verified +Flow actors before the next Terminal Benchmark live API drill. + +Risk: + +L1 + +Depends on: + +`WS-POL-001-10` + +Allowed files: + +```text +backend/alembic/versions/*_actor_identity_profile_registry.py +backend/app/api/router.py +backend/app/api/deps/auth.py +backend/app/api/routes/demo.py +backend/app/api/routes/auth.py +backend/app/db/models.py +backend/app/modules/actors/__init__.py +backend/app/modules/actors/models.py +backend/app/modules/actors/repository.py +backend/app/modules/actors/schemas.py +backend/app/modules/actors/service.py +backend/app/modules/tasks/models.py +backend/app/modules/tasks/repository.py +backend/app/modules/tasks/router.py +backend/app/modules/tasks/schemas.py +backend/app/modules/tasks/service.py +backend/tests/test_actors.py +backend/tests/test_alembic.py +backend/tests/test_auth.py +backend/tests/test_tasks.py +backend/scripts/week1_dry_run.py +backend/scripts/week1_api_e2e.py +backend/scripts/week2_api_e2e.py +examples/terminal_benchmark/terminal_benchmark_api_e2e.py +docs/architecture_data_model.md +docs/architecture_lockdown.md +docs/architecture_system_architecture.md +docs/glossary.md +docs/operations_roles_permissions.md +docs/spec_chunk_2_auth_actor_boundary.md +docs/spec_chunk_4_task_queue_assignment.md +.agent-loop/LOOP_STATE.md +.agent-loop/WORK_QUEUE.md +.agent-loop/REVIEW_LOG.md +.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md +.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-11-actor-identity-profile-registry.md +.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-* +``` + +Not allowed: + +```text +Workstream-owned login, signup, password reset, password storage, primary auth sessions, or API-key auth +Flow token verifier replacement +route access from persisted profile rows instead of verified token roles +task/submission/checker/review/revision/payment/reputation behavior changes +agent runtime, project setup pipeline, Celery, storage, frontend, demo feature, or blockchain changes +``` + +Acceptance criteria: + +- `ActorIdentity` and `ActorProfile` models/tables exist with unique identity + and profile constraints. +- Existing worker/reviewer profile rows are backfilled into the shared profile + model and the separate profile tables, ORM models, and repository authority + paths stop owning profile state. +- Seeded migration tests prove worker/reviewer profile backfill preserves + profile type, status, skill tags, scope, and table removal. +- Flow token verification remains pure. Actor registration uses a separate + actors service/repository boundary. +- Route authorization remains token-derived. +- Profile status values are explicit. `observed` is audit/display metadata, + `active` is explicit workflow eligibility, and profile status is never route + permission. +- Observation refresh preserves existing `active` and `disabled` profile + status unless an explicit audited profile workflow changes status. +- Worker claim requires both verified worker token role and active worker + profile. +- Stored profiles without matching token roles do not grant operator, worker, + reviewer, or project-manager access. +- Stale backend demo/script imports of old worker/reviewer profile models are + removed, rewired, or retired so the shared actor profile model is the only + profile authority. +- Stale backend script/example calls to `/api/v1/demo/worker-profile` are + removed, rewired to `POST /api/v1/workers/me/profile`, or explicitly retired. +- Verification includes a stale helper scan for old profile model imports and + the removed demo worker-profile endpoint. + +Required reviewers: + +senior engineering, QA/test, security/auth, product/ops, architecture, docs, +reuse/dedup, test delta. + +Human review focus: + +The shared actor/profile model removes duplicated profile storage without +turning persisted profiles into auth or permission authority. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md index 42af727..5eb96cf 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md @@ -3,15 +3,14 @@ ## Current Status `WS-POL-001-01`, `WS-POL-001-02`, `WS-POL-001-03`, `WS-POL-001-04`, -`WS-POL-001-05`, `WS-POL-001-06`, `WS-POL-001-07`, `WS-POL-001-08`, and -`WS-POL-001-09` are merged to `main`. `WS-POL-001-10` is open as PR #72 from -`codex/ws-pol-001-10-pre-submit-hardening` after the user's explicit start -signal for the first five pre-submit hardening fixes from the real Terminal -Benchmark API drill. +`WS-POL-001-05`, `WS-POL-001-06`, `WS-POL-001-07`, `WS-POL-001-08`, +`WS-POL-001-09`, and `WS-POL-001-10` are merged to `main`. `WS-POL-001-11` is +in active planning/spec contract review and is implementation-inactive until +human review approves the actor identity/profile implementation boundary. ## Active Chunk -`WS-POL-001-10` - Pre-Submit Live Drill Hardening. +`WS-POL-001-11` contract review. Implementation is inactive. ## Chunk Status @@ -26,13 +25,14 @@ Benchmark API drill. | `WS-POL-001-07` | Merged | `codex/ws-pol-001-07-task-contract-cleanup` | 68 | Removes task-owned `required_files`/`required_evidence` from request/response/model/migration and keeps artifact requirements project-policy driven. | | `WS-POL-001-08` | Merged | `codex/ws-pol-001-08-celery-project-setup` | 69 | Makes guide/source capture enqueue Celery pre-submit setup automatically: sufficiency first, blocked stops, draft submission artifact policy next; removes remaining construction-state compatibility surfaces. | | `WS-POL-001-09` | Merged | `codex/ws-pol-001-09-openai-agent-sdk-only` | 71 | Removes the production `local_fixture` project setup runtime and old runtime selector; keeps deterministic test behavior in explicit test-local fakes only. | -| `WS-POL-001-10` | PR open; CodeRabbit fixes applied locally | `codex/ws-pol-001-10-pre-submit-hardening` | 72 | Hardens duplicate guide-version conflicts, guide-create source snapshots, active-guide checker summaries, worker self-profile onboarding, and failed pre-submit audit evidence. | +| `WS-POL-001-10` | Merged | `codex/ws-pol-001-10-pre-submit-hardening` | 72 | Hardens duplicate guide-version conflicts, guide-create source snapshots, active-guide checker summaries, worker self-profile onboarding, and failed pre-submit audit evidence. | +| `WS-POL-001-11` | Contract review active; implementation inactive | `codex/ws-pol-001-11-actor-identity-profile-contract` | - | Defines local Workstream actor identity and actor profile registries for verified Flow actors before the next live API drill. | ## Blockers | Blocker | Owner | Next action | |---|---|---| -| None | - | Push evidence-rebound follow-up, rerun PR #72 CI, then human checkpoint for `WS-POL-001-10`. | +| None | - | Review and merge the `WS-POL-001-11` contract before implementation starts. | ## Follow-Ups @@ -41,3 +41,4 @@ Benchmark API drill. | Add public revision lifecycle coverage instead of direct `needs_revision` test setup | Test-delta review | High for `WS-POL-001-05` | | Add focused `0007 -> 0006` downgrade assertion for locked-context columns and constraints | QA/test-delta review | Medium follow-up | | Extract shared artifact path and forbidden-pattern helpers before further checker-policy expansion | Reuse/dedup review | Medium follow-up | +| Add profile-level audit events if actor/profile changes become reputation-sensitive | Security review on PR #72 | Medium follow-up | diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-11-actor-identity-profile-registry.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-11-actor-identity-profile-registry.md new file mode 100644 index 0000000..8e79b9b --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-11-actor-identity-profile-registry.md @@ -0,0 +1,448 @@ +# Chunk Contract: WS-POL-001-11 - Actor Identity And Profile Registry + +## Parent initiative + +WS-POL-001 - Submission Artifact Policy Foundation + +## Goal + +Add local Workstream actor identity and actor profile registries for verified +Flow actors so every operator, worker, reviewer, project manager, project +owner, and system actor has a durable Workstream identity anchor and a shared +profile model for workflow metadata before task assignments, audit events, and +later reputation records attach to them. + +## Why this chunk exists + +`WS-POL-001-10` made worker profile creation a real API flow, but it also made +the remaining profile gap obvious: Workstream currently resolves `ActorContext` +from Flow tokens and stores actor snapshots on worker profiles and audit +events, while worker/reviewer/admin/project-manager/project-owner profile state +would otherwise drift into separate one-off implementations. + +The correct boundary is: + +```text +Flow token verification +-> trusted ActorContext +-> Workstream ActorIdentity is created/refreshed +-> Workstream ActorProfile rows are created/refreshed for observed profile types +-> workflow records attach to actor_id and profile context where needed +``` + +`ActorIdentity` and `ActorProfile` are not authentication. Flow remains the auth +provider. Workstream still does not own login, signup, password reset, password +storage, primary auth sessions, or role authority. Route access is still +decided from the verified token for each request. + +Persisted `ActorProfile.profile_type` is metadata, eligibility, audit context, +and later routing/reputation context. It may be required as an additional +workflow condition, but it must never grant access without the matching verified +token role. + +## Approved plan reference + +- INTENT: + `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/INTENT.md` +- PLAN: + `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/PLAN.md` +- CHUNK_MAP: + `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md` + +## Risk class + +L1 + +## SLA + +P1 + +## Allowed implementation files + +```text +backend/alembic/versions/*_actor_identity_profile_registry.py +backend/app/api/router.py +backend/app/api/deps/auth.py +backend/app/api/routes/demo.py +backend/app/api/routes/auth.py +backend/app/db/models.py +backend/app/modules/actors/__init__.py +backend/app/modules/actors/models.py +backend/app/modules/actors/repository.py +backend/app/modules/actors/schemas.py +backend/app/modules/actors/service.py +backend/app/modules/tasks/models.py +backend/app/modules/tasks/repository.py +backend/app/modules/tasks/router.py +backend/app/modules/tasks/schemas.py +backend/app/modules/tasks/service.py +backend/tests/test_actors.py +backend/tests/test_alembic.py +backend/tests/test_auth.py +backend/tests/test_tasks.py +backend/scripts/week1_dry_run.py +backend/scripts/week1_api_e2e.py +backend/scripts/week2_api_e2e.py +examples/terminal_benchmark/terminal_benchmark_api_e2e.py +docs/architecture_data_model.md +docs/architecture_lockdown.md +docs/architecture_system_architecture.md +docs/glossary.md +docs/operations_roles_permissions.md +docs/spec_chunk_2_auth_actor_boundary.md +docs/spec_chunk_4_task_queue_assignment.md +.agent-loop/LOOP_STATE.md +.agent-loop/WORK_QUEUE.md +.agent-loop/REVIEW_LOG.md +.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/CHUNK_MAP.md +.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md +.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-11-actor-identity-profile-registry.md +.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-* +``` + +## Not allowed + +```text +Workstream-owned login, signup, password reset, password storage, primary auth sessions, or API-key auth +Flow token verification provider replacement +roles or permissions sourced from ActorIdentity instead of the verified token +roles or permissions sourced from ActorProfile instead of the verified token +automatic task claiming, reviewing, payment, or project access from profiles alone +worker/reviewer routing changes beyond moving profile storage to ActorProfile and preserving current worker-profile API behavior +task lifecycle, submission, checker, review, revision, payment, or reputation behavior changes +agent runtime, project setup pipeline, Celery, storage, frontend, or demo feature changes +blockchain, ERC-8004, ERC-8183, settlement, marketplace, or external source adapters +``` + +Demo/backend script/example edits are allowed only to remove, retire, or rewire +stale `WorkerProfile`/`ReviewerProfile` imports and stale +`/api/v1/demo/worker-profile` calls that would break application import or +local evidence scripts after the shared actor profile migration. + +## Expected design + +### ActorIdentity + +Create a new `ActorIdentity` persistence model with one row per stable +Workstream actor id. + +Required fields: + +- `actor_id` +- `external_subject` +- `external_issuer` +- `display_name` +- `email` +- `last_seen_roles` +- `last_claim_snapshot` +- `auth_source` +- `is_dev_auth` +- `first_seen_at` +- `last_seen_at` +- `updated_at` + +Rules: + +- `actor_id` remains derived from external issuer and subject. +- `external_issuer + external_subject` must be unique. +- `ActorIdentity` is updated only from trusted `ActorContext`. +- `last_seen_roles` and `last_claim_snapshot` are observability snapshots, not + permission authority. +- `display_name` and `email` may be null and may be refreshed from the latest + verified token. +- System actors such as `workstream_system` must be representable without + weakening Flow-user behavior. + +### ActorProfile + +Create a shared `ActorProfile` persistence model for role/profile metadata and +eligibility. + +Required fields: + +- `id` +- `actor_id` +- `profile_type` +- `status` +- `skill_tags` +- `scope_type` +- `scope_id` +- `profile_metadata` +- `created_at` +- `updated_at` + +Initial `profile_type` values: + +- `worker` +- `reviewer` +- `admin` +- `project_manager` +- `project_owner` + +`project_owner` is a profile type and source/contact relationship. It is not a +route-authorizing role in v0.1. Workstream creates scoped +`ActorProfile(profile_type="project_owner")` rows from trusted project setup +source/contact data or trusted relationship claims when present. That profile +still cannot approve policies, manage projects, or access operator routes +without a route-authorizing token role such as `admin` or `project_manager`. + +Rules: + +- `actor_id + profile_type + scope_type + scope_id` is unique. +- Global profiles use `scope_type = "global"` and `scope_id = "global"`. +- Initial status values are `observed`, `active`, and `disabled`. +- `observed` means Workstream has seen the actor through a verified token role + and keeps metadata for audit/display only. It is not workflow eligibility. +- `active` means the actor completed the explicit workflow for that profile + type. For this chunk, only the worker self-profile API can make a worker + profile active. +- `disabled` means the profile exists but cannot satisfy workflow eligibility. +- Worker and reviewer skill tags live on `ActorProfile`, not in duplicated + worker/reviewer tables long term. +- `profile_metadata` is structured JSON for non-authoritative profile details; + it must not store secrets. +- `ActorProfile.status = "active"` can be a workflow eligibility condition, but + it cannot grant route access without a matching verified token role. +- A verified token role may create or refresh the matching profile type for + observability and future routing with `status = "observed"`. It must not + create unrelated profile types and must not mark profiles active by auth + observation alone. +- Observation refresh must preserve existing `active` and `disabled` statuses. + It may refresh metadata and last-seen details, but it must not downgrade an + active profile to observed or revive a disabled profile. +- Any transition to `active` or `disabled` must happen through the profile + type's explicit service workflow and must write audit evidence. +- Worker profile creation remains an explicit worker-owned API call in this + chunk. Auth alone can refresh observed admin/project-manager profile records, + but it must not mark a worker or reviewer eligible without the relevant + profile workflow. +- `project_owner` is scoped source/contact metadata for the organization or + person that supplied project material or business terms. It is not the same + as `project_manager`, and it does not approve Workstream's machine-readable + internal policy schema unless the verified token also carries an authorized + Workstream role such as `admin` or `project_manager`. + +### Auth Boundary + +`get_current_actor` remains the pure Flow-token verification boundary. It must +not write database rows. + +Add a separate actor-registration boundary, such as +`get_registered_actor`, backed by `backend/app/modules/actors/service.py` and +`backend/app/modules/actors/repository.py`, for routes that need the actor +registry side effect. That dependency resolves the trusted actor through +`get_current_actor`, then creates or refreshes `ActorIdentity` and allowed +non-eligibility observed profile rows before route services run. + +The actor service may refresh non-eligibility observed profile rows for +route-authorizing roles carried by the verified token, such as `admin` and +`project_manager`. It may also create or refresh scoped non-route relationship +profiles such as `project_owner` from trusted project setup/source-contact data +or trusted relationship claims when those claims exist. Worker and reviewer +eligibility require their explicit profile workflows. + +This must be fail-closed: + +- missing or invalid bearer token still returns unauthorized +- failed actor identity/profile persistence returns a server error, not a + silently unaudited request +- dev/mock auth still cannot run in production and remains visible through + `auth_source` and `is_dev_auth` + +### Route Access And Workflow Eligibility + +Route authorization must always check verified token roles from `ActorContext`. +Profile checks are additional workflow eligibility checks. + +Examples: + +```text +Admin route: + require "admin" in verified token roles + optionally record/refresh ActorProfile(profile_type="admin") + +Worker profile API: + require "worker" in verified token roles + upsert ActorProfile(profile_type="worker", status="active", skill_tags=...) + +Task claim: + require "worker" in verified token roles + require active ActorProfile(profile_type="worker") + +Reviewer action later: + require "reviewer" in verified token roles + require active ActorProfile(profile_type="reviewer") +``` + +This preserves the security boundary and still gives Workstream one shared +profile implementation. + +### Compatibility Boundary + +The implementation path is fixed: + +- create `actor_identities` +- create `actor_profiles` +- backfill actor/profile rows from existing `worker_profiles` and + `reviewer_profiles` rows when those rows exist +- remove the separate `worker_profiles` and `reviewer_profiles` tables as + independent profile stores +- remove old worker/reviewer profile ORM models and repository authority paths; + after migration, task services must read and write profile state through the + actor module +- keep the public `POST /api/v1/workers/me/profile` route, but make it read and + write `ActorProfile(profile_type="worker")` + +No new compatibility layer may treat `worker_profiles` or `reviewer_profiles` +as profile authority after this migration. Do not keep wrapper tables, shadow +tables, views, or dual-write paths in v0.1. If the implementation discovers a +hard migration blocker, stop and return for human review instead of keeping two +profile sources of truth. + +## Acceptance criteria + +- [ ] Alembic creates `actor_identities` with uniqueness on `actor_id` and + `external_issuer + external_subject`. +- [ ] Alembic creates `actor_profiles` with uniqueness on `actor_id`, + `profile_type`, `scope_type`, and `scope_id`. +- [ ] Alembic backfills existing worker/reviewer profile rows into + `actor_identities` and `actor_profiles`, then removes the separate + `worker_profiles` and `reviewer_profiles` tables as independent profile + stores. +- [ ] Worker/reviewer ORM models and repositories stop owning profile state; + services use the actor module as the profile authority. +- [ ] SQLAlchemy metadata imports the new actor models so Alembic does not + drift. +- [ ] Migration tests prove the new tables, unique constraints, metadata + imports, and downgrade/upgrade path expected by the repo. +- [ ] Seeded migration tests prove existing `worker_profiles` and + `reviewer_profiles` rows are backfilled into `ActorIdentity` and + `ActorProfile` with expected `profile_type`, `status`, `skill_tags`, + `scope_type`, and `scope_id`, and that old profile tables are removed. +- [ ] API requests updated in this chunk create or refresh `ActorIdentity` from + trusted `ActorContext` through the explicit actor-registration + dependency. Routes outside this chunk may continue using pure + `get_current_actor` until they are deliberately migrated. +- [ ] Registration-enabled API requests create or refresh observed + non-eligibility profile rows for verified token roles without granting + access from the stored row. +- [ ] `GET /api/v1/auth/me` proves actor identity/profile persistence without + adding any Workstream-owned auth session behavior. +- [ ] Repeated requests by the same external issuer/subject update last-seen + identity/profile metadata without creating duplicate actor rows. +- [ ] Parametrized tests cover profile creation/refresh for `worker`, + `reviewer`, `admin`, and `project_manager` from trusted token roles, + plus scoped `project_owner` profile creation from trusted project + source/contact data or relationship claims, including profile type, + status, scope, and duplicate prevention. +- [ ] Tests prove token-observed admin, project-manager, worker, and reviewer + profiles default to `observed`, scoped project-owner relationship + profiles default to `observed`, and observed profiles do not satisfy + worker or reviewer workflow eligibility. +- [ ] Tests prove observation refresh preserves existing `active` and + `disabled` statuses unless an explicit audited profile workflow changes + status. +- [ ] Worker profile creation writes the shared `ActorProfile` worker row while + still requiring the worker role and explicit worker profile API call. +- [ ] Worker claim requires both verified `worker` token role and active + `ActorProfile(profile_type="worker")`. +- [ ] A persisted active `worker` profile without the verified `worker` token + role cannot claim tasks. +- [ ] Persisted active `admin` or `project_manager` profiles without matching + verified token roles cannot access operator/project-manager routes. +- [ ] Reviewer profile storage uses the shared `ActorProfile` implementation + when reviewer eligibility is touched, without adding new review lifecycle + behavior in this chunk. +- [ ] Reviewer eligibility activation workflow is explicitly deferred unless a + current API path already touches reviewer profile storage; auth + observation alone must never create active reviewer eligibility. +- [ ] Profile status, skill-tag, scope, and eligibility changes write audit + evidence sufficient for an operator to reconstruct why an actor was + eligible at claim/review time. +- [ ] Non-worker actors can get an `ActorIdentity` and an observed profile for + their token role, but cannot claim tasks or create worker profiles. +- [ ] Request bodies remain fail-closed; clients cannot spoof `actor_id`, + `external_subject`, `external_issuer`, roles, email, or display name into + the registry. +- [ ] Negative over-posting tests prove spoofed identity, role, email, and + display-name fields submitted to `POST /api/v1/workers/me/profile` and + registration-touched protected routes are rejected or ignored, and + persisted identity/profile values remain token-derived. +- [ ] Docs clearly distinguish Flow auth, `ActorContext`, `ActorIdentity`, + `ActorProfile`, route authorization, and workflow eligibility. +- [ ] The next Terminal Benchmark live API drill must use + `POST /api/v1/workers/me/profile` for worker profile setup. It must not + use `/api/v1/demo/worker-profile`. +- [ ] Stale demo/backend evidence helpers no longer import or write old + `WorkerProfile` or `ReviewerProfile` models after those stores are + removed. They are either rewired to `ActorProfile` or explicitly retired. +- [ ] `backend/scripts/week1_api_e2e.py`, + `backend/scripts/week2_api_e2e.py`, and + `examples/terminal_benchmark/terminal_benchmark_api_e2e.py` no longer + call `/api/v1/demo/worker-profile`; they either use + `POST /api/v1/workers/me/profile` or are explicitly retired. + +## Verification commands + +```bash +cd backend && .venv/bin/python -m ruff check app/api/deps/auth.py app/api/routes/auth.py app/modules/actors app/modules/tasks/models.py app/modules/tasks/repository.py app/modules/tasks/router.py app/modules/tasks/schemas.py app/modules/tasks/service.py tests/test_actors.py tests/test_alembic.py tests/test_auth.py tests/test_tasks.py +cd backend && .venv/bin/python -m pytest tests/test_alembic.py tests/test_actors.py tests/test_auth.py -q +cd backend && .venv/bin/python -m pytest tests/test_tasks.py -q +cd backend && .venv/bin/docstr-coverage app/api app/modules/actors app/modules/tasks --config .docstr.yaml +! rg -n 'WorkerProfile|ReviewerProfile|/api/v1/demo/worker-profile' backend/scripts examples/terminal_benchmark backend/app/api/routes/demo.py backend/app/modules +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_markdown_links.py +git diff --check +``` + +## Required reviewers + +Every listed reviewer must end with one exact result value: + +- `PASS` +- `PASS AFTER FIXES` +- `PASS WITH LOW RISKS` +- `N/A - with approved reason` +- `FAIL` + +Critical and High findings require `FAIL` until fixed. Medium findings must be +included in `PASS WITH LOW RISKS` or `FAIL` based on remediation effort and +human-decision need; they must not be omitted. + +Required: + +- [ ] senior engineering +- [ ] QA/test +- [ ] security/auth +- [ ] product/ops +- [ ] architecture +- [ ] docs +- [ ] reuse/dedup +- [ ] test delta + +## Human review focus + +- `ActorIdentity` is a local registry of verified Flow actors, not Workstream + auth. +- `ActorProfile` is shared workflow metadata and eligibility, not permission + authority. +- Role/permission checks still use the verified token claims for the current + request. +- Worker profile eligibility remains explicit; auth alone does not make a + worker eligible to claim tasks. +- The implementation gives us a clean base for the next live Terminal Benchmark + drill and later human-agent/reputation linkage. + +## Stop conditions + +Stop and escalate if: + +- making the registry work requires Workstream-owned login/session behavior +- any route starts trusting persisted roles instead of verified token roles +- worker or reviewer eligibility becomes automatic from auth alone +- migration scope requires rewriting existing task/submission/checker records +- post-submit, review, revision, payment, reputation, blockchain, frontend, or + agent-runtime scope becomes necessary +- tests or CI must be weakened to pass +- same blocker remains after 2 repair attempts +- secrets or production data are needed diff --git a/docs/architecture_data_model.md b/docs/architecture_data_model.md index b1bc430..3732fcf 100644 --- a/docs/architecture_data_model.md +++ b/docs/architecture_data_model.md @@ -7,9 +7,8 @@ The v0.1 persistence layer uses SQLAlchemy 2.x async models, Alembic migrations, ## Entity Overview ```text -Actor - WorkerProfile - ReviewerProfile +ActorIdentity + ActorProfile Project ProjectGuide @@ -42,27 +41,79 @@ Task AuditEvent ``` -## Actor +## Actor Identity And Profile Fields: -- `id` +- `actor_id` - `external_subject` - `external_issuer` - `email` - `display_name` -- `role` -- `claim_snapshot` +- `last_seen_roles` +- `last_claim_snapshot` - `auth_source` -- `created_at` +- `is_dev_auth` +- `first_seen_at` - `last_seen_at` +- `updated_at` + +Actor identity comes from external Flow authentication. `external_subject` plus +`external_issuer` is the stable identity binding. Email is profile metadata and +must not be treated as the primary identity. + +Workstream keeps `ActorIdentity` rows for local workflow continuity, audit +display, profile linkage, assignments, and later reputation records. It does +not own password authentication, primary login sessions, or role authority. +Route authorization still uses the verified token roles in the current +`ActorContext`. + +`ActorProfile` is the shared profile and eligibility model attached to an +`ActorIdentity`. + +Fields: + +- `id` +- `actor_id` +- `profile_type` - `status` +- `skill_tags` +- `scope_type` +- `scope_id` +- `profile_metadata` +- `created_at` +- `updated_at` + +Initial profile types: + +- worker +- reviewer +- admin +- project_manager +- project_owner + +Profile rows are metadata and workflow eligibility records. They do not grant +route access without the matching verified token role. A project owner profile +is scoped source/contact metadata and is not the same as a project manager +permission role. -Actor identity comes from external Flow authentication. `external_subject` plus `external_issuer` is the stable identity binding. Email is profile metadata and must not be treated as the primary identity. +Initial profile statuses: -Workstream can keep actor/profile records for permissions, assignments, reputation, and audit display, but it does not own password authentication or primary login sessions. +- `observed`: created or refreshed from a verified token role for audit/display + metadata only; it is not workflow eligibility. +- `active`: created by an explicit profile workflow and allowed to satisfy + workflow eligibility checks for that profile type. +- `disabled`: retained for audit but blocked from workflow eligibility. -Roles: +Auth observation alone may create `observed` profiles, but it must not mark a +worker or reviewer profile `active`. Route access always comes from the current +verified token roles, not from profile status. + +`project_owner` is a scoped profile/contact relationship, not a route role. It +is created from trusted project setup or relationship claims when present; it is +not listed as a permission role and does not grant operator access. + +Verified token roles: - admin - project_manager @@ -75,33 +126,16 @@ Roles: ## WorkerProfile -Fields: - -- `actor_id` -- `display_name` -- `skill_tags` -- `accepted_count` -- `needs_revision_count` -- `rejected_count` -- `paid_total` -- `pending_payout_total` -- `reputation_score` -- `status` +Worker profile behavior is represented by `ActorProfile(profile_type="worker")`. +The public worker profile API remains worker-owned, but the persistence model is +the shared actor profile model. ## ReviewerProfile -Fields: - -- `actor_id` -- `skill_tags` -- `reviews_completed` -- `accept_count` -- `needs_revision_count` -- `reject_count` -- `overturned_count` -- `average_turnaround_hours` -- `review_quality_score` -- `status` +Reviewer profile behavior is represented by +`ActorProfile(profile_type="reviewer")`. Reviewer eligibility must be explicit; +observing a reviewer token role alone does not make the actor eligible for +review workflow. ## Project diff --git a/docs/architecture_system_architecture.md b/docs/architecture_system_architecture.md index 0c3d009..244340b 100644 --- a/docs/architecture_system_architecture.md +++ b/docs/architecture_system_architecture.md @@ -87,9 +87,18 @@ Auth policy: - Production auth uses a Flow token verifier adapter. - Local development may use a mock verifier only outside production. - Actor identity is based on stable token subject and issuer, not email. -- Workstream may keep local actor/profile records for workflow state, permissions, audit display, and reputation, but those records do not replace Flow as the auth source. -- Role and permission checks use trusted Flow claims, local Workstream role mappings, or a documented combination of both. -- Routers depend on a single current-actor dependency; permission checks live in service or policy code so workflow rules do not scatter across HTTP handlers. +- Workstream may keep local actor/profile records for workflow state, + workflow eligibility, audit display, and reputation, but those records do not + replace Flow as the auth source and do not grant route access. +- Route role and permission checks use trusted Flow token claims for the + current request. Local actor/profile records may add workflow eligibility + conditions, such as an active worker profile before task claim, but they are + not route permission authority. +- Routers use the pure current-actor dependency when they only need verified + Flow identity. Routes that need local actor registry side effects use a + separate registration dependency that first resolves the current actor, then + records or refreshes local actor/profile metadata. Permission checks live in + service or policy code so workflow rules do not scatter across HTTP handlers. - Audit records preserve actor id, external subject, issuer, role/claim context, and whether dev/mock auth was used when relevant. ## Component Responsibilities diff --git a/docs/glossary.md b/docs/glossary.md index b94943c..2544ff9 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -16,6 +16,34 @@ repository docs, examples, rubrics, task instructions, base payout or payment policy inputs, or other project-specific source material. The project owner does not author or approve Workstream's machine-readable internal policy schema. +## ActorContext + +The trusted per-request actor object resolved from a verified Flow token. It +contains the current actor id, external subject, issuer, roles, claim snapshot, +auth source, and display metadata. Route authorization uses this current token +context, not persisted profile rows. + +## ActorIdentity + +Workstream's local durable identity record for a verified Flow actor. It is +keyed by the stable actor id derived from external issuer and subject. It +supports audit display, profile linkage, assignment history, and later +reputation records. It is not Workstream-owned authentication. + +## ActorProfile + +Workstream's shared profile and workflow eligibility record attached to an +`ActorIdentity`. Initial profile types include worker, reviewer, admin, +project_manager, and project_owner. A profile can store status, skill tags, +scope, and metadata, but it does not grant route access without the matching +verified token role. A project_owner profile is scoped source/contact metadata, +not project-manager authority. + +`observed` profile status is audit/display metadata from verified token +observation. `active` profile status means an explicit profile workflow made +that profile eligible for the relevant Workstream workflow. Neither status is +route permission. + ## Source Where a task came from. In v0.1, sources are manual creation, controlled markdown import, or controlled CSV import. diff --git a/docs/operations_roles_permissions.md b/docs/operations_roles_permissions.md index 9f4e921..44f59a6 100644 --- a/docs/operations_roles_permissions.md +++ b/docs/operations_roles_permissions.md @@ -6,7 +6,11 @@ Workstream needs explicit permissions from the first version because review, pay ## Roles -Roles come from trusted Flow token claims, local Workstream role mappings, or an explicitly documented combination of both. The backend resolves those into a current actor context before protected workflow actions run. +Route authorization roles come from trusted Flow token claims resolved into the +current `ActorContext`. Local Workstream `ActorIdentity` and `ActorProfile` +records may mirror observed roles, profile state, skill tags, scope, and +eligibility metadata, but persisted profile rows do not grant route access by +themselves. | Role | Purpose | | --- | --- | @@ -17,6 +21,17 @@ Roles come from trusted Flow token claims, local Workstream role mappings, or an | Finance | Updates payout status and payment references. | | Auditor | Reads records and audit logs without modifying work. | +`project_owner` is not a route-authorizing Workstream role in v0.1. A project +owner is the external or internal source of project material or business terms. +It may be recorded as scoped actor profile/contact metadata, but it does not +approve Workstream machine-readable policies unless the verified token also +carries an authorized Workstream role such as admin or project manager. + +Actor profile status is a workflow condition, not route permission. An +`observed` profile only records that Workstream saw the actor through a verified +token. An `active` profile can satisfy the profile side of a workflow gate, but +the route still requires the matching role in the current verified token. + ## Permission Matrix | Action | Admin | Project Manager | Worker | Reviewer | Finance | Auditor | @@ -24,8 +39,8 @@ Roles come from trusted Flow token claims, local Workstream role mappings, or an | Create project | yes | no | no | no | no | no | | Edit project guide | yes | yes | no | no | no | no | | Create task | yes | yes | no | no | no | no | -| Claim task | yes | yes | yes | no | no | no | -| Submit task | yes | no | own task only | no | no | no | +| Claim task | no | no | yes | no | no | no | +| Submit task | no | no | own task only | no | no | no | | Run checkers | yes | yes | own submission | no | no | no | | Review submission | yes | no | no | yes | no | no | | Review own submission | no | no | no | no | no | no | @@ -43,10 +58,16 @@ Roles come from trusted Flow token claims, local Workstream role mappings, or an - A reviewer cannot mark payment as paid. - Finance cannot change review decisions. - Project managers cannot silently override checker failures. +- Admin and project-manager operational intervention must use a separate + audited override path. It must not masquerade as worker task claiming. - Admin overrides must create an audit event with reason and evidence. ## First-Version Enforcement -The first version enforces permissions in application service or policy code, not directly inside routers. The database records actor IDs, external subject, issuer, role/claim context, and auth source for important events so later role enforcement can be audited. +The first version enforces permissions in application service or policy code, +not directly inside routers. The database records actor IDs, external subject, +issuer, role/claim context, auth source, actor identity, and actor profile +context for important events so later route decisions and workflow eligibility +can be audited. Development auth, if enabled, must be impossible to use in production and must be visible in audit context. diff --git a/docs/spec_chunk_4_task_queue_assignment.md b/docs/spec_chunk_4_task_queue_assignment.md index cf80f79..494a0a7 100644 --- a/docs/spec_chunk_4_task_queue_assignment.md +++ b/docs/spec_chunk_4_task_queue_assignment.md @@ -56,6 +56,11 @@ New tables: - `task_assignments` - `audit_events` +Note: `WS-POL-001-11` supersedes the separate worker/reviewer profile storage +from this earlier chunk. Worker and reviewer profile behavior moves to the +shared `ActorProfile` model, while task assignment and audit records keep using +stable actor ids. + Task records store: - project id From bc65665d0a01be3efabe58f9a478fc820875fbb8 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 6 Jul 2026 13:00:01 +0100 Subject: [PATCH 2/4] Add actor profile contract review evidence --- .agent-loop/LOOP_STATE.md | 12 +- .../STATUS.md | 14 +- .../WS-POL-001-11-internal-review-evidence.md | 108 ++++++++++ .../reviews/WS-POL-001-11-pr-trust-bundle.md | 185 ++++++++++++++++++ 4 files changed, 308 insertions(+), 11 deletions(-) create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-internal-review-evidence.md create mode 100644 .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-pr-trust-bundle.md diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index af4f40a..af9f75c 100644 --- a/.agent-loop/LOOP_STATE.md +++ b/.agent-loop/LOOP_STATE.md @@ -6,13 +6,13 @@ - Active planning chunk: `WS-POL-001-11` - Actor Identity And Profile Registry - Active implementation chunk: none - Branch: `codex/ws-pol-001-11-actor-identity-profile-contract` -- Status: `WS-POL-001-10` merged through PR #72. `WS-POL-001-11` is in active - planning/spec contract review for Workstream's local actor identity and - profile registry. Implementation is inactive until human review approves the - contract. +- Status: `WS-POL-001-10` merged through PR #72. `WS-POL-001-11` contract, + internal review evidence, and PR trust bundle are prepared for human review. + Implementation is inactive until human review approves the contract. - Last merged implementation SHA: `cc78f2a` - Last merge commit: `1bbde47` -- Current gate: `WS-POL-001-11` contract review +- Current gate: `WS-POL-001-11` PR/external review, then human contract + approval - Next chunk: `WS-POL-001-11` is contract-only until human review approves the implementation boundary @@ -112,3 +112,5 @@ blockchain, frontend, or agent-runtime behavior. - `WS-POL-001-11` is the next planned bounded chunk. It should add local Workstream actor identity and actor profile registries for verified Flow actors before the next Terminal Benchmark live API drill. +- `WS-POL-001-11` internal review evidence is tracked at `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-internal-review-evidence.md`. +- `WS-POL-001-11` PR trust bundle is tracked at `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-pr-trust-bundle.md`. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md index 5eb96cf..3aa4209 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md @@ -4,13 +4,15 @@ `WS-POL-001-01`, `WS-POL-001-02`, `WS-POL-001-03`, `WS-POL-001-04`, `WS-POL-001-05`, `WS-POL-001-06`, `WS-POL-001-07`, `WS-POL-001-08`, -`WS-POL-001-09`, and `WS-POL-001-10` are merged to `main`. `WS-POL-001-11` is -in active planning/spec contract review and is implementation-inactive until -human review approves the actor identity/profile implementation boundary. +`WS-POL-001-09`, and `WS-POL-001-10` are merged to `main`. `WS-POL-001-11` +contract evidence is ready for PR/external review and human approval. +Implementation remains inactive until human review approves the actor +identity/profile implementation boundary. ## Active Chunk -`WS-POL-001-11` contract review. Implementation is inactive. +`WS-POL-001-11` PR/external review, then human contract approval. +Implementation is inactive. ## Chunk Status @@ -26,13 +28,13 @@ human review approves the actor identity/profile implementation boundary. | `WS-POL-001-08` | Merged | `codex/ws-pol-001-08-celery-project-setup` | 69 | Makes guide/source capture enqueue Celery pre-submit setup automatically: sufficiency first, blocked stops, draft submission artifact policy next; removes remaining construction-state compatibility surfaces. | | `WS-POL-001-09` | Merged | `codex/ws-pol-001-09-openai-agent-sdk-only` | 71 | Removes the production `local_fixture` project setup runtime and old runtime selector; keeps deterministic test behavior in explicit test-local fakes only. | | `WS-POL-001-10` | Merged | `codex/ws-pol-001-10-pre-submit-hardening` | 72 | Hardens duplicate guide-version conflicts, guide-create source snapshots, active-guide checker summaries, worker self-profile onboarding, and failed pre-submit audit evidence. | -| `WS-POL-001-11` | Contract review active; implementation inactive | `codex/ws-pol-001-11-actor-identity-profile-contract` | - | Defines local Workstream actor identity and actor profile registries for verified Flow actors before the next live API drill. | +| `WS-POL-001-11` | Internal review complete; PR pending | `codex/ws-pol-001-11-actor-identity-profile-contract` | - | Defines local Workstream actor identity and actor profile registries for verified Flow actors before the next live API drill. | ## Blockers | Blocker | Owner | Next action | |---|---|---| -| None | - | Review and merge the `WS-POL-001-11` contract before implementation starts. | +| None | - | Open PR for `WS-POL-001-11`, wait for external review, then human review decides whether to merge the contract before implementation starts. | ## Follow-Ups diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-internal-review-evidence.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-internal-review-evidence.md new file mode 100644 index 0000000..47d7559 --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-internal-review-evidence.md @@ -0,0 +1,108 @@ +# Internal Review Evidence: WS-POL-001-11 + +## Chunk + +WS-POL-001-11 + +open sub-agent sessions: none + +valid findings addressed: yes + +## Reviewed Revision + +Reviewed code SHA: b769b70c07d22f7a802f6d4219201e7bbd2a3ab0 + +Reviewed working diff digest before evidence files: +86a15c53c7e407b902094212a5c08143e9c91cf154544e38ddbfc5e9f123983d + +Reviewed at: 2026-07-06T11:57:16Z + +Reviewer run IDs: senior-engineering-review-019f3741-9fa2-72a2-93b2-58d9e043fd57, qa-test-review-019f3741-ac4e-7f83-b0c7-3acb174e0058, security-auth-review-019f3747-7bf3-7b63-b093-cf8ba17d1183, product-ops-review-019f3747-82e8-7f13-95c9-e8339f8f08e6, architecture-review-019f3741-befb-77a2-bd85-0c43766b2219, docs-review-019f3741-cdda-72c3-8cf6-4dc2a78260c1, reuse-dedup-review-019f3741-de89-7742-b300-74f54eb1558a, test-delta-review-019f3741-efdd-72e2-9b07-d8dfe2836a79 + +After the reviewed SHA, only evidence and status files changed. + +## Reviewed Change + +Scope: + +- Defines the `WS-POL-001-11` actor identity and profile registry contract. +- Keeps Flow token verification as the route authorization source. +- Separates pure `get_current_actor` from the actor-registration boundary. +- Defines shared `ActorIdentity` and `ActorProfile` semantics for worker, + reviewer, admin, project manager, and project owner records. +- Requires old worker/reviewer profile stores to be migrated into the shared + actor profile model with no wrapper, shadow table, or dual-write authority. +- Clarifies profile statuses: `observed`, `active`, and `disabled`. +- Requires worker claim to remain worker-only and require both a verified + worker token role and active worker profile. +- Adds implementation scope for stale demo/script helper cleanup so the next + Terminal Benchmark drill uses `POST /api/v1/workers/me/profile`. + +No backend implementation code changed in this PR. + +## Reviewer Results + +| Reviewer | Result | Blocking findings | Notes | +|---|---:|---|---| +| senior engineering | PASS | None | Confirmed final commit scope is implementable and contract file is tracked. | +| QA/test | PASS | None | Confirmed seeded migration backfill tests, stale helper scan, full task tests, and negative auth/profile tests are required. | +| security/auth | PASS | None | Confirmed persisted profiles do not grant route access, token roles remain authority, and spoofing/dev-auth requirements are present. | +| product/ops | PASS | None | Confirmed worker/reviewer/operator semantics, project-owner metadata boundary, and Terminal Benchmark drill route are clear. | +| architecture | PASS | None | Confirmed actor registration boundary, old profile authority removal, and scoped demo/script cleanup are feasible. | +| CI integrity | N/A - with approved reason | N/A | No CI workflow, package script, dependency, lint, typecheck, or coverage configuration changed. | +| docs | PASS | None | Confirmed contract, chunk map, data model, system architecture, glossary, roles, and task spec are aligned. | +| reuse/dedup | PASS | None | Confirmed one actor module/profile authority and no wrapper/shadow/dual-write profile path in the contract. | +| test delta | PASS | None | Confirmed no tests were changed and the implementation contract requires the right regression coverage. | + +## Valid Findings Addressed + +- Committed the new chunk contract so the PR cannot omit the active contract. +- Clarified `project_owner` as scoped source/contact metadata, not a + route-authorizing Workstream role. +- Changed task claim permissions to worker-only and documented that + admin/project-manager intervention must use a separate audited override path. +- Added `is_dev_auth` to the `ActorIdentity` data model. +- Defined `observed`, `active`, and `disabled` profile statuses. +- Required observation refreshes to preserve existing `active` and `disabled` + status unless an explicit audited profile workflow changes status. +- Narrowed actor-registration side effects to routes updated in the chunk; + routes outside the chunk may continue using pure `get_current_actor`. +- Fixed system architecture wording so local actor/profile records are not + permission authority and registration dependency is separate from pure auth. +- Required seeded migration tests proving old worker/reviewer rows backfill + into `ActorIdentity` and `ActorProfile`, including profile type, status, + skill tags, scope, and old table removal. +- Added stale helper scope for `backend/scripts/week1_api_e2e.py`, + `backend/scripts/week2_api_e2e.py`, and + `examples/terminal_benchmark/terminal_benchmark_api_e2e.py`. +- Added a stale helper scan for old `WorkerProfile`/`ReviewerProfile` imports + and `/api/v1/demo/worker-profile` calls. +- Added `FAIL` to the contract's allowed reviewer results and stated that + Critical/High findings require `FAIL` until fixed. +- Added a forward note to the older Chunk 4 spec that `WS-POL-001-11` + supersedes separate worker/reviewer profile storage. + +## Commands Run + +```bash +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_markdown_links.py +git diff --check HEAD~1..HEAD +git diff --check +``` + +Results: + +- Stale wording scan: passed. +- Markdown link check: passed for 11 changed Markdown files. +- Diff whitespace checks: passed. +- Local XLSX export: not present. + +## Remaining Risks + +- This PR is contract/process/docs only. The next implementation PR still needs + to prove the migration, actor service, profile route behavior, stale helper + removal, and live API drill with real API calls. +- Existing protected routers are not all migrated to actor registration in this + chunk. That is intentional; only routes touched in the implementation chunk + get the registration side effect. diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-pr-trust-bundle.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-pr-trust-bundle.md new file mode 100644 index 0000000..a941fdc --- /dev/null +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-pr-trust-bundle.md @@ -0,0 +1,185 @@ +# PR Trust Bundle: WS-POL-001-11 + +## Chunk + +`WS-POL-001-11` - Actor Identity And Profile Registry + +## Goal + +Approve the implementation contract for Workstream's local actor identity and +shared actor profile registry before coding the next backend chunk. + +## Human-Approved Intent + +The user asked to avoid adding only a worker profile path and instead define +one shared actor/profile model for the current actor types: worker, reviewer, +admin, project manager, and project owner. + +Chunk contract: + +- `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-11-actor-identity-profile-registry.md` + +## What Changed + +- Added a `WS-POL-001-11` chunk contract. +- Updated loop state, work queue, initiative status, and chunk map after PR #72 + merged. +- Updated data model, glossary, system architecture, roles/permissions, and the + older task queue spec to align with the actor identity/profile contract. +- Clarified that Flow token roles authorize routes and persisted profiles only + support workflow eligibility, audit, display, and later reputation context. +- Clarified `project_owner` as scoped source/contact metadata, not a + route-authorizing Workstream role. +- Required old worker/reviewer profile storage to migrate into shared + `ActorProfile` authority without wrappers, shadow tables, or dual writes. +- Added implementation scope for stale demo/script helper cleanup so live API + drills use `POST /api/v1/workers/me/profile`. + +## Why It Changed + +The live Terminal Benchmark drill showed worker profile setup was now real, but +the broader actor model still needed to be locked before implementation. Without +this contract, worker, reviewer, admin, and project-owner metadata could drift +into separate one-off models or, worse, become hidden permission authority. + +## Design Chosen + +- `ActorIdentity` is the local durable record for a verified Flow actor. +- `ActorProfile` is the shared profile and workflow eligibility record. +- `get_current_actor` stays pure token verification. +- A separate registration dependency records actor/profile metadata when a + route deliberately needs that side effect. +- Route access is always derived from the current verified Flow token role. +- Profile status values are `observed`, `active`, and `disabled`. +- Task claim requires both verified `worker` token role and active worker + profile. + +## Alternatives Rejected + +- Separate worker/reviewer/admin profile tables: rejected because they create + duplicated profile authority. +- Persisted profiles as route permissions: rejected because Flow token claims + are the route authorization source. +- Automatic worker/reviewer eligibility from token observation: rejected + because eligibility must come from explicit profile workflows. +- Keeping old worker/reviewer profile wrappers: rejected because v0.1 is still + under construction and should not preserve stale compatibility layers. + +## Scope Control + +No backend implementation code changed. No migrations, APIs, services, tests, +CI, frontend, payment, reputation, review lifecycle, checker runtime, agent +runtime, Celery behavior, blockchain behavior, or object storage behavior were +implemented. + +## Product Behavior + +- No runtime Workstream product behavior changed in this PR. +- Product review decisions remain only `accept`, `needs_revision`, and + `reject`. +- The PR only locks the implementation contract for the next backend chunk. + +## Acceptance Criteria Proof + +- Actor identity/profile contract exists and is tracked in git. +- Public docs now distinguish Flow auth, `ActorContext`, `ActorIdentity`, + `ActorProfile`, route authorization, and workflow eligibility. +- Permissions docs make task claim worker-only. +- Architecture docs no longer imply local actor/profile records grant route + permissions. +- The contract requires migration backfill tests, spoofing tests, persisted + profile privilege-escalation tests, status preservation tests, stale helper + scans, and full task test coverage. + +## Tests/Checks Run + +```bash +python3 scripts/check_stale_workstream_wording.py +python3 scripts/check_markdown_links.py +git diff --check HEAD~1..HEAD +git diff --check +``` + +Result summary: + +- Stale wording scan: passed. +- Markdown link check: passed for 11 changed Markdown files. +- Diff whitespace checks: passed. +- Local XLSX export: not present. + +## Test Delta + +- Tests added: none. +- Tests modified: none. +- Tests removed/skipped: none. +- The next implementation contract explicitly requires the relevant tests. + +## CI Integrity + +- Coverage threshold unchanged. +- Lint configuration unchanged. +- Typecheck configuration unchanged. +- No workflow weakening. +- No package script weakening. +- No new GitHub Actions. +- No dependency changes. + +## Reviewer Results + +Internal review evidence: + +- `.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-11-internal-review-evidence.md` + +Reviewed code SHA: `b769b70c07d22f7a802f6d4219201e7bbd2a3ab0` + +Reviewed diff digest before evidence files: +`86a15c53c7e407b902094212a5c08143e9c91cf154544e38ddbfc5e9f123983d` + +Reviewer run IDs: see `WS-POL-001-11-internal-review-evidence.md`. + +| Reviewer | Result | Blocking findings | Notes | +|---|---:|---|---| +| senior engineering | PASS | None | Final scope and implementability confirmed. | +| QA/test | PASS | None | Required migration, profile, stale-helper, and task-test coverage confirmed. | +| security/auth | PASS | None | Token authority and profile non-permission boundary confirmed. | +| product/ops | PASS | None | Worker/reviewer/operator semantics confirmed. | +| architecture | PASS | None | Module boundary and demo/script cleanup scope confirmed. | +| CI integrity | N/A - with approved reason | N/A | No CI/workflow/package/dependency/config changes. | +| docs | PASS | None | Standing docs and chunk map align with the contract. | +| reuse/dedup | PASS | None | Single actor module/profile authority confirmed. | +| test delta | PASS | None | No tests changed; planned coverage is explicit. | + +## External Review + +External review has not run yet. CodeRabbit and GitHub checks should run after +the PR is opened. + +## Remaining Risks + +- The next PR must implement and prove the contract with real backend code and + tests. +- Existing routes outside the next chunk may continue using pure + `get_current_actor` until they are deliberately migrated. +- The next Terminal Benchmark drill must use the real worker profile endpoint, + not `/api/v1/demo/worker-profile`. + +## Follow-Up Work + +- Implement `WS-POL-001-11` after human approval. +- Run the Terminal Benchmark live API drill with real HTTP requests after the + actor/profile registry implementation merges. + +## Human Review Focus + +Please inspect: + +- The route authority boundary: Flow token role first, profile eligibility + second. +- The old worker/reviewer profile migration and no-compatibility stance. +- The `project_owner` wording as scoped source/contact metadata. +- The stale demo/script cleanup scope for the next live API drill. + +## Human Merge Ownership + +Only the user can approve and merge this PR. Codex must not merge it without +explicit user approval for that specific PR. From 2dcd849073517faf210cef9c0b9ee0a72b2d9d66 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 6 Jul 2026 13:02:48 +0100 Subject: [PATCH 3/4] Update actor profile contract PR status --- .agent-loop/LOOP_STATE.md | 10 +++++----- .../STATUS.md | 12 ++++++------ 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index af9f75c..c20a986 100644 --- a/.agent-loop/LOOP_STATE.md +++ b/.agent-loop/LOOP_STATE.md @@ -6,13 +6,13 @@ - Active planning chunk: `WS-POL-001-11` - Actor Identity And Profile Registry - Active implementation chunk: none - Branch: `codex/ws-pol-001-11-actor-identity-profile-contract` -- Status: `WS-POL-001-10` merged through PR #72. `WS-POL-001-11` contract, - internal review evidence, and PR trust bundle are prepared for human review. - Implementation is inactive until human review approves the contract. +- Status: `WS-POL-001-10` merged through PR #72. `WS-POL-001-11` is open as + PR #73 with contract, internal review evidence, and PR trust bundle prepared + for human review. Implementation is inactive until human review approves the + contract. - Last merged implementation SHA: `cc78f2a` - Last merge commit: `1bbde47` -- Current gate: `WS-POL-001-11` PR/external review, then human contract - approval +- Current gate: PR #73 external review, then human contract approval - Next chunk: `WS-POL-001-11` is contract-only until human review approves the implementation boundary diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md index 3aa4209..4f6f85a 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md @@ -4,14 +4,14 @@ `WS-POL-001-01`, `WS-POL-001-02`, `WS-POL-001-03`, `WS-POL-001-04`, `WS-POL-001-05`, `WS-POL-001-06`, `WS-POL-001-07`, `WS-POL-001-08`, -`WS-POL-001-09`, and `WS-POL-001-10` are merged to `main`. `WS-POL-001-11` -contract evidence is ready for PR/external review and human approval. -Implementation remains inactive until human review approves the actor +`WS-POL-001-09`, and `WS-POL-001-10` are merged to `main`. `WS-POL-001-11` is +open as PR #73 with contract evidence ready for external review and human +approval. Implementation remains inactive until human review approves the actor identity/profile implementation boundary. ## Active Chunk -`WS-POL-001-11` PR/external review, then human contract approval. +`WS-POL-001-11` PR #73 external review, then human contract approval. Implementation is inactive. ## Chunk Status @@ -28,13 +28,13 @@ Implementation is inactive. | `WS-POL-001-08` | Merged | `codex/ws-pol-001-08-celery-project-setup` | 69 | Makes guide/source capture enqueue Celery pre-submit setup automatically: sufficiency first, blocked stops, draft submission artifact policy next; removes remaining construction-state compatibility surfaces. | | `WS-POL-001-09` | Merged | `codex/ws-pol-001-09-openai-agent-sdk-only` | 71 | Removes the production `local_fixture` project setup runtime and old runtime selector; keeps deterministic test behavior in explicit test-local fakes only. | | `WS-POL-001-10` | Merged | `codex/ws-pol-001-10-pre-submit-hardening` | 72 | Hardens duplicate guide-version conflicts, guide-create source snapshots, active-guide checker summaries, worker self-profile onboarding, and failed pre-submit audit evidence. | -| `WS-POL-001-11` | Internal review complete; PR pending | `codex/ws-pol-001-11-actor-identity-profile-contract` | - | Defines local Workstream actor identity and actor profile registries for verified Flow actors before the next live API drill. | +| `WS-POL-001-11` | PR open; internal review complete | `codex/ws-pol-001-11-actor-identity-profile-contract` | 73 | Defines local Workstream actor identity and actor profile registries for verified Flow actors before the next live API drill. | ## Blockers | Blocker | Owner | Next action | |---|---|---| -| None | - | Open PR for `WS-POL-001-11`, wait for external review, then human review decides whether to merge the contract before implementation starts. | +| None | - | Wait for PR #73 external review, then human review decides whether to merge the contract before implementation starts. | ## Follow-Ups From 9f7219f556fa6d125da1b0aa260009ef507b4019 Mon Sep 17 00:00:00 2001 From: Abiorh001 Date: Mon, 6 Jul 2026 13:05:58 +0100 Subject: [PATCH 4/4] Make actor profile contract memory merge-safe --- .agent-loop/LOOP_STATE.md | 10 +++++----- .../STATUS.md | 16 ++++++++-------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.agent-loop/LOOP_STATE.md b/.agent-loop/LOOP_STATE.md index c20a986..716299e 100644 --- a/.agent-loop/LOOP_STATE.md +++ b/.agent-loop/LOOP_STATE.md @@ -6,13 +6,13 @@ - Active planning chunk: `WS-POL-001-11` - Actor Identity And Profile Registry - Active implementation chunk: none - Branch: `codex/ws-pol-001-11-actor-identity-profile-contract` -- Status: `WS-POL-001-10` merged through PR #72. `WS-POL-001-11` is open as - PR #73 with contract, internal review evidence, and PR trust bundle prepared - for human review. Implementation is inactive until human review approves the - contract. +- Status: `WS-POL-001-10` merged through PR #72. `WS-POL-001-11` has contract, + internal review evidence, and PR trust bundle prepared for human review. + Implementation is inactive until the contract is approved and the user gives + an explicit implementation start signal. - Last merged implementation SHA: `cc78f2a` - Last merge commit: `1bbde47` -- Current gate: PR #73 external review, then human contract approval +- Current gate: human review of `WS-POL-001-11` contract - Next chunk: `WS-POL-001-11` is contract-only until human review approves the implementation boundary diff --git a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md index 4f6f85a..ca6d56c 100644 --- a/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md +++ b/.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md @@ -4,15 +4,15 @@ `WS-POL-001-01`, `WS-POL-001-02`, `WS-POL-001-03`, `WS-POL-001-04`, `WS-POL-001-05`, `WS-POL-001-06`, `WS-POL-001-07`, `WS-POL-001-08`, -`WS-POL-001-09`, and `WS-POL-001-10` are merged to `main`. `WS-POL-001-11` is -open as PR #73 with contract evidence ready for external review and human -approval. Implementation remains inactive until human review approves the actor -identity/profile implementation boundary. +`WS-POL-001-09`, and `WS-POL-001-10` are merged to `main`. `WS-POL-001-11` +contract evidence is ready for external review and human approval. +Implementation remains inactive until human review approves the actor +identity/profile implementation boundary and the user gives an explicit +implementation start signal. ## Active Chunk -`WS-POL-001-11` PR #73 external review, then human contract approval. -Implementation is inactive. +`WS-POL-001-11` contract review. Implementation is inactive. ## Chunk Status @@ -28,13 +28,13 @@ Implementation is inactive. | `WS-POL-001-08` | Merged | `codex/ws-pol-001-08-celery-project-setup` | 69 | Makes guide/source capture enqueue Celery pre-submit setup automatically: sufficiency first, blocked stops, draft submission artifact policy next; removes remaining construction-state compatibility surfaces. | | `WS-POL-001-09` | Merged | `codex/ws-pol-001-09-openai-agent-sdk-only` | 71 | Removes the production `local_fixture` project setup runtime and old runtime selector; keeps deterministic test behavior in explicit test-local fakes only. | | `WS-POL-001-10` | Merged | `codex/ws-pol-001-10-pre-submit-hardening` | 72 | Hardens duplicate guide-version conflicts, guide-create source snapshots, active-guide checker summaries, worker self-profile onboarding, and failed pre-submit audit evidence. | -| `WS-POL-001-11` | PR open; internal review complete | `codex/ws-pol-001-11-actor-identity-profile-contract` | 73 | Defines local Workstream actor identity and actor profile registries for verified Flow actors before the next live API drill. | +| `WS-POL-001-11` | Internal review complete; implementation inactive | `codex/ws-pol-001-11-actor-identity-profile-contract` | 73 | Defines local Workstream actor identity and actor profile registries for verified Flow actors before the next live API drill. | ## Blockers | Blocker | Owner | Next action | |---|---|---| -| None | - | Wait for PR #73 external review, then human review decides whether to merge the contract before implementation starts. | +| None | - | Human review decides whether to accept the contract before implementation starts. | ## Follow-Ups