Expose task context and submission requirement APIs

[Abiorh001]

PR Trust Bundle: WS-POL-001-13

Chunk

WS-POL-001-13 - Task context and submission requirement APIs.

Goal

Expose task context and submission requirements through authorized HTTP APIs so
workers and operators no longer need to infer locked requirements from failures
or inspect Postgres during the next live drill.

Human-approved intent

Chunk contract:

• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-13-task-context-submission-requirements-apis.md

The user approved exposing worker-safe task context, exact submission
requirements, and operator-only locked provenance APIs before rerunning the
Terminal Benchmark drill.

What changed

Implemented APIs 8-10 only:

• GET /api/v1/tasks/{task_id}/work-context
• GET /api/v1/tasks/{task_id}/submission-requirements
• GET /api/v1/tasks/{task_id}/locked-context

The implementation also redacts existing worker-visible task reads so
GET /tasks/{task_id} cannot bypass the worker-safe projection.

Why it changed

The Terminal Benchmark drill showed that setup and task policy state was still
too dependent on direct database inspection. This chunk exposes the
already-locked task context through authorized APIs while preserving the rule
that runtime uses stamped policy references, not recomputed current project
state.

Design chosen

Task context APIs read the task's already-stamped locked context. They do not
recompute from the current active guide or current project policy.

Worker-facing APIs return:

• safe task summary
• project and locked guide summary
• stamped payment terms
• review/revision guide-version references
• lifecycle next actions
• exact submission packet fields, including package_hash
• artifact, evidence, storage, packaging, hash, and attestation requirements

Operator-only locked-context returns full locked provenance for admin and
project_manager.

Authorization:

• work-context: existing task visibility for admin, project_manager, or
  eligible/assigned worker.
• submission-requirements: existing task visibility for admin,
  project_manager, or eligible/assigned worker.
• locked-context: admin or project_manager only.
• Persisted actor profiles do not grant route authorization; token-derived
  roles remain the route gate.

Alternatives rejected

• Recomputing task requirements from the current active guide at read time:
  rejected because tasks must expose the stamped context they already locked.
• Exposing compiled bundles, checker configs, source refs, or private policy
  internals to workers: rejected because worker-facing APIs should show what
  must be submitted, not checker authority.
• Continuing to inspect Postgres during the live drill: rejected because the
  next drill must prove the public/operator API surface.

Scope control

Allowed files changed

• backend/app/modules/tasks/router.py
• backend/app/modules/tasks/schemas.py
• backend/app/modules/tasks/service.py
• backend/scripts/api_contract_e2e.py
• backend/tests/test_tasks.py
• docs/architecture_data_model.md
• docs/architecture_system_architecture.md
• docs/glossary.md
• docs/operations_project_operating_manual.md
• docs/roadmap_status.md
• .agent-loop/LOOP_STATE.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-13-internal-review-evidence.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-13-external-review-response.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-13-pr-trust-bundle.md

Files outside scope

None.

Product Behavior

• No Workstream product behavior changed.
• Product behavior changed and is explained here:

Workers and operators can now inspect task context and submission requirements
through authorized APIs. Worker responses are intentionally redacted. Operators
with admin or project_manager can inspect full locked provenance.

Acceptance criteria proof

• Worker-safe task context API exists and reads locked context.
  Evidence: test_task_context_apis_return_worker_requirements_and_operator_provenance.
• Submission requirements API returns exact packet, artifact, evidence,
  storage, packaging, hash, and attestation requirements.
  Evidence: test_task_context_apis_return_worker_requirements_and_operator_provenance
  and scripts/api_contract_e2e.py.
• Operator locked-context API is restricted to admin and
  project_manager.
  Evidence: test_task_context_apis_return_worker_requirements_and_operator_provenance.
• Missing, stale, or malformed locked context fails closed.
  Evidence: test_submission_requirements_fail_closed_on_hash_consistent_malformed_policy_shape.
• Worker-facing task reads remain redacted.
  Evidence: test_worker_task_response_redacts_locked_policy_hashes.

Tests/checks run

cd backend && .venv/bin/python -m ruff check app tests scripts
python3 scripts/check_stale_workstream_wording.py
python3 scripts/check_markdown_links.py
git diff --check
cd backend && .venv/bin/pytest tests/test_tasks.py::test_worker_task_response_redacts_locked_policy_hashes tests/test_tasks.py::test_assigned_worker_submits_v1_and_task_moves_to_submitted tests/test_tasks.py::test_task_context_apis_return_worker_requirements_and_operator_provenance tests/test_tasks.py::test_submission_requirements_fail_closed_on_hash_consistent_malformed_policy_shape -q
cd backend && WORKSTREAM_DATABASE_URL=postgresql+asyncpg://workstream:workstream@localhost:5433/workstream_test .venv/bin/python scripts/api_contract_e2e.py
cd backend && .venv/bin/pytest tests/test_tasks.py
cd backend && .venv/bin/pytest tests/test_tasks.py::test_submission_requirements_fail_closed_on_hash_consistent_malformed_policy_shape -q
cd backend && .venv/bin/python -m ruff check tests/test_tasks.py

Result summary:

Focused task-context and worker-redaction regressions: 4 passed
API contract real API E2E: passed with the three new task-context endpoints
Full task suite: 81 passed in 743.67s
CodeRabbit regression pytest: 1 passed
Ruff: passed
Stale wording: passed
Markdown links: passed
git diff --check: passed

Test delta

Tests added

• Added task API coverage for worker-facing work context and submission
  requirements.
• Added operator-only locked-context API coverage.
• Added fail-closed locked-context validation coverage.
• Added regression coverage for worker redaction on existing task reads.
• Extended the real API contract drill to call the three new endpoints.

Tests modified

• Updated test_submission_requirements_fail_closed_on_hash_consistent_malformed_policy_shape
  after CodeRabbit review to capture the compiled bundle before deleting the
  ORM row.

Tests removed/skipped

None.

CI integrity

• Coverage threshold unchanged
• Lint unchanged
• Typecheck unchanged
• No workflow weakening
• No package script weakening
• No unpinned new GitHub Action
• Checkout credential persistence unchanged

External review

External review response file:

• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-13-external-review-response.md

Source	Status	Notes
CodeRabbit	Addressed locally	One valid test-maintainability nitpick and one PR-description warning were fixed.
GitHub checks	Pending rerun	Existing checks passed before this external-review response commit; they must rerun after push.

Reviewer results

Reviewed implementation SHA: f533f1a572a38d4e8ecd34ff6316885c6c6b1016

Reviewed at: 2026-07-08T02:09:55Z

Reviewer run IDs:

• senior engineering: 019f3f6d-441f-7340-9bcc-ef92155d956d
• QA/test: 019f3f6d-4986-7612-a7a7-9457a2182d0b
• security/auth: 019f3f6d-4fea-7890-a372-a261d2482b91
• product/ops: 019f3f6d-5758-79d3-a7d4-3d58933064da
• docs: 019f3f6d-6062-7590-8358-3bc0766e935d
• reuse/dedup: original internal review evidence
• test delta: 019f3f6d-685a-7300-82ab-966c3c034976

Reviewer	Result	Blocking findings	Notes
senior engineering	PASS	None	Confirmed the CodeRabbit test fix is minimal.
QA/test	PASS WITH LOW RISKS	None	Confirmed coverage is not weakened.
security/auth	PASS	None	Confirmed no auth or data-leakage risk in the delta.
product/ops	PASS	None	Confirmed external review stays separate from internal evidence and human merge ownership remains intact.
architecture	PASS	None	Original internal review result.
CI integrity	N/A - with approved reason	None	No CI/workflow/package-script files changed in the external-review response delta.
docs	PASS AFTER FIXES	None	Initial template-format finding was fixed.
reuse/dedup	PASS WITH LOW RISKS	None	Original internal review result.
test delta	PASS	None	Confirmed the test still proves fail-closed malformed policy behavior.

All sub-agent sessions were closed before final reporting.

Remaining risks

• Worker-facing locked-context errors include internal field names, but no
  values, hashes, source refs, bundles, or configs.
• Required packet field constants mirror SubmissionCreate and should be kept
  in sync until a shared schema-derived helper is extracted.
• Full no-DB Terminal Benchmark proof remains assigned to WS-POL-001-14.

Follow-up work

• WS-POL-001-14: replace public submission lock wording with finalize,
  define system actor audit semantics, and rerun the Terminal Benchmark proof
  without DB inspection.
• Later cleanup: extract a shared schema-derived helper for required packet
  fields if another caller needs the same constants.

Human review focus

Please inspect:

• Confirm worker-facing requirements are complete enough to submit without
  exposing internal checker authority.
• Confirm existing GET /tasks/{task_id} redaction is acceptable for workers.
• Confirm locked-context exposes the right operator provenance and remains
  restricted to admin and project_manager.
• Confirm task_locked_context_invalid is the right public error code for
  missing/stale/malformed task locked context.

Human ownership

• I can explain what changed.
• I can explain why it changed.
• I know what could break.
• I accept the remaining risks.
• The user explicitly approved this specific PR for merge.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds worker-safe task work-context and submission-requirements endpoints, an operator-only locked-context endpoint, locked-context validation and redaction in task service logic, expanded tests and API contract checks, and matching process-tracking and documentation updates.

Changes

Task Context APIs

Layer / File(s)	Summary
Process and review tracking updates .agent-loop/LOOP_STATE.md, .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md, .agent-loop/REVIEW_LOG.md, docs/roadmap_status.md, .agent-loop/initiatives/.../reviews/*	Updates chunk status, review records, roadmap notes, and review evidence/trust-bundle documents for WS-POL-001-13.
Task context response schemas and routes backend/app/modules/tasks/schemas.py, backend/app/modules/tasks/router.py	Adds worker-safe and operator-only task context schemas, new domain error schemas, and GET routes for /work-context, /submission-requirements, and /locked-context.
Locked-context validation and response building backend/app/modules/tasks/service.py	Adds locked-context validation, task service methods, new error/dataclass types, and task-body redaction for private provenance fields.
Tests and API contract drill backend/tests/test_tasks.py, backend/scripts/api_contract_e2e.py	Expands task tests and the API contract drill for visibility, redaction, fail-closed behavior, and locked-context assertions.
Architecture and operations documentation docs/architecture_data_model.md, docs/architecture_system_architecture.md, docs/glossary.md, docs/operations_project_operating_manual.md	Documents the new task context API projections, ownership, glossary definitions, and screening-gate usage.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Worker
  participant TaskRouter
  participant TaskService
  participant Database
  Worker->>TaskRouter: GET /tasks/{task_id}/work-context
  TaskRouter->>TaskService: get_task_work_context(actor, task_id)
  TaskService->>Database: load task and locked-context rows
  TaskService->>TaskService: validate locked context
  TaskService-->>TaskRouter: TaskWorkContextResponse
  TaskRouter-->>Worker: 200 response

Loading

Possibly related issues

• WS-POL-001-03: Lock task and submission runtime to compiled policy context #31: Implements task locked-context enforcement and policy-derived task/submission APIs aligned with this PR’s new task context endpoints.

Possibly related PRs

• Flow-Research/workstream#9: Introduced the task module/service structure that these new task-context routes build on.
• Flow-Research/workstream#10: Established submission-artifact-policy foundations that the new submission-requirements and locked-context responses depend on.
• Flow-Research/workstream#28: Added the guide/policy and compiled checker foundations consumed by the new locked-context validation.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly matches the main change: new task context and submission requirement APIs.
Description check	✅ Passed	The PR description largely follows the trust-bundle template and includes the required scope, rationale, evidence, tests, and review sections.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-pol-001-13-task-context-apis

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

backend/tests/test_tasks.py (1)

1446-1457: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Reading pre_submit_policy.compiled_bundle after delete()+flush() is fragile.

The instance is deleted and flushed at Lines 1446-1447, then its compiled_bundle is dereferenced at Line 1455. This only works because the column is already cached in the instance state; any attribute expiry/refresh on a deleted row raises ObjectDeletedError. Capture the bundle before deleting to avoid relying on that.

♻️ Capture the bundle before deletion

         compiler_version = pre_submit_policy.compiler_version
+        original_compiled_bundle = dict(pre_submit_policy.compiled_bundle)
         await session.delete(pre_submit_policy)
         await session.flush()

         malformed_policy = {
             **effective_policy.effective_policy,
             "schema_version": ["not", "a", "string"],
         }
         malformed_policy_hash = canonical_json_hash(malformed_policy)
         malformed_bundle = {
-            **pre_submit_policy.compiled_bundle,
+            **original_compiled_bundle,
             "effective_policy_hash": malformed_policy_hash,
         }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@backend/tests/test_tasks.py` around lines 1446 - 1457, Capture
pre_submit_policy.compiled_bundle before calling session.delete() and
session.flush() in the test that builds malformed_bundle, then use that saved
bundle when constructing malformed_bundle. This avoids dereferencing a deleted
ORM instance after flush and keeps the test from depending on cached state;
locate the fix around the pre_submit_policy, malformed_policy, and
malformed_bundle setup.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@backend/tests/test_tasks.py`:
- Around line 1446-1457: Capture pre_submit_policy.compiled_bundle before
calling session.delete() and session.flush() in the test that builds
malformed_bundle, then use that saved bundle when constructing malformed_bundle.
This avoids dereferencing a deleted ORM instance after flush and keeps the test
from depending on cached state; locate the fix around the pre_submit_policy,
malformed_policy, and malformed_bundle setup.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7f9e897a-4e62-492f-922c-083065dcea2a

📥 Commits

Reviewing files that changed from the base of the PR and between 46e74de and 071f848.

📒 Files selected for processing (14)

• .agent-loop/LOOP_STATE.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/STATUS.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-13-internal-review-evidence.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-13-pr-trust-bundle.md
• backend/app/modules/tasks/router.py
• backend/app/modules/tasks/schemas.py
• backend/app/modules/tasks/service.py
• backend/scripts/api_contract_e2e.py
• backend/tests/test_tasks.py
• docs/architecture_data_model.md
• docs/architecture_system_architecture.md
• docs/glossary.md
• docs/operations_project_operating_manual.md
• docs/roadmap_status.md