Harden pre-submit live drill flows

[Abiorh001]

PR Trust Bundle: WS-POL-001-10

Chunk

WS-POL-001-10 - Pre-Submit Live Drill Hardening

Goal

Fix the concrete pre-submit setup and intake gaps found during the real
Terminal Benchmark API drill before continuing post-submit work.

Human-Approved Intent

The user explicitly asked to fix the first five pre-submit issues before moving
forward:

1. Duplicate guide versions must not bubble as 500s.
2. Worker profile setup must be possible through a real authenticated API, not
   direct DB seeding.
3. Project guide creation must support captured source material and
   representative task examples so agents are not forced to reason from guide
   markdown alone.
4. Active guide reads must show enough project pre-submit checker context for
   operators.
5. Failed pre-submit submission attempts must create no submission but still
   leave durable operator audit evidence.

Chunk contract:

• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/chunks/WS-POL-001-10-pre-submit-live-drill-hardening.md

What Changed

• Added GuideVersionConflict and mapped duplicate guide insert conflicts to
  HTTP 409.
• Added optional source_snapshot to guide creation, reusing the existing
  source snapshot capture and automatic setup enqueue path.
• Added checker_names and checker_configs to the active-guide
  PreSubmitCheckerPolicySummaryResponse; compiled_bundle remains excluded.
• Added WorkerProfileUpsertRequest, WorkerProfileResponse, and
  POST /api/v1/workers/me/profile.
• Added worker skill-tag normalization and fail-closed validation.
• Added durable pre_submission_check_failed task audit events for blocked
  submission-create attempts.
• Updated tests for all five acceptance criteria and reviewer-requested edge
  cases.
• Updated standing docs for worker self-profile setup and failed pre-submit
  audit semantics.
• Updated loop state/status and added this chunk contract.

Why It Changed

The live Terminal Benchmark drill showed the lifecycle was mostly wired, but
parts still behaved like tests rather than a real Workstream workflow. This
chunk removes those rough edges while keeping the architecture project-scoped:
one active guide/source snapshot/effective project policy/project
PreSubmitCheckerPolicy, with tasks locking references to that context.

Design Chosen

• Keep guide source material capture in the project module and reuse
  _create_guide_source_snapshot_model.
• Keep worker profile creation in the task module because claiming and worker
  assignment already depend on WorkerProfile.
• Derive worker identity only from verified Flow actor context.
• Keep failed pre-submit outcomes as pre_submission_checker_failed for
  submission-create responses and pre_submission_check_failed for internal
  task audit evidence.
• Expose checker names/configs to operators but not compiled checker bundle
  bodies.

Alternatives Rejected

• Direct DB seeding for workers in real flows: rejected because it does not
  represent a human/API workflow.
• Reintroducing guide-owned artifact fields: rejected because
  SubmissionArtifactPolicy remains the artifact intake contract.
• Creating a submission row for failed pre-submit attempts: rejected because a
  failed pre-submit check means no valid submission exists yet.
• Broadly documenting all APIs in this chunk: rejected; only docs affected by
  changed public/operator behavior were updated.

Scope Control

No migrations, checker internals, project-agent runtime changes, post-submit
policy redesign, review lifecycle, revision lifecycle, payment, reputation,
blockchain, frontend, or demo behavior was changed.

Product Behavior

• Workers can create or refresh their own active profile before claiming a task.
• Workers without an active profile still cannot claim.
• Project operators can see checker names/configs on active guide reads.
• Blocked pre-submit submission-create attempts return
  pre_submission_checker_failed, create no submission, and write
  pre_submission_check_failed audit evidence for project operators.
• Product review decisions remain only accept, needs_revision, and reject.

Acceptance Criteria Proof

• Duplicate guide version conflict: tested by
  test_duplicate_guide_version_returns_conflict.
• Guide-create source snapshot material: tested by
  test_guide_creation_accepts_source_snapshot_items_for_agent_material.
• Active-guide checker summary: tested by
  test_guide_activation_and_active_guide_retrieval.
• Worker self-profile create/refresh and claim: tested by
  test_worker_can_create_profile_before_claiming_task.
• Worker profile fail-closed validation and role gate: tested by
  test_worker_profile_request_is_fail_closed_and_validated and
  test_worker_profile_requires_worker_role.
• Failed pre-submit audit without submission: tested by
  test_pre_submit_failure_writes_audit_event_without_submission.

Tests/Checks Run

cd backend && .venv/bin/python -m ruff check app/modules/projects/schemas.py app/modules/projects/service.py app/modules/tasks/router.py app/modules/tasks/schemas.py app/modules/tasks/service.py tests/test_projects.py tests/test_tasks.py
cd backend && .venv/bin/python -m pytest tests/test_projects.py -k 'duplicate_guide_version_returns_conflict or guide_creation_accepts_source_snapshot_items_for_agent_material or guide_activation_and_active_guide_retrieval' -q
cd backend && .venv/bin/python -m pytest tests/test_tasks.py -k 'worker_can_create_profile_before_claiming_task or worker_profile_request_is_fail_closed_and_validated or worker_profile_requires_worker_role or worker_without_profile_cannot_claim_ready_task or pre_submit_failure_writes_audit_event_without_submission' -q
cd backend && .venv/bin/docstr-coverage app/modules/projects app/modules/tasks --config .docstr.yaml
python3 scripts/check_markdown_links.py
python3 scripts/check_stale_workstream_wording.py
git diff --check
cd backend && .venv/bin/python -m pytest tests/test_projects.py tests/test_tasks.py tests/test_checkers.py -q

Result summary:

• ruff: passed.
• Focused project tests: 3 passed.
• Focused task tests: 5 passed.
• Docstring coverage: 100.0%.
• Markdown link check: passed for 7 changed Markdown files.
• Stale wording scan: passed.
• Diff whitespace check: passed.
• Full project/task/checker suite: 310 passed.

Reviewer Results

Internal review evidence:

• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-10-internal-review-evidence.md

Reviewed base SHA: 8a524dec9de1fabb7ae6a605d45ae8ab3778a32c

Reviewed diff digest before evidence files:
67e2b7561d3688f6e588e5abe09317104da3bbd66ec97231f9f49b886801903b

Reviewer	Result	Blocking findings	Notes
senior engineering	PASS WITH LOW RISKS	None	Findings on conflict mapping and skill tags addressed.
QA/test	PASS WITH LOW RISKS	None	Requested worker profile fail-closed test; addressed.
security/auth	PASS	None	Verified Flow-derived identity, role gate, and bounded audit exposure.
product/ops	PASS WITH LOW RISKS	None	Skill-tag normalization concern addressed.
architecture	PASS WITH LOW RISKS	None	Broad IntegrityError concern addressed.
reuse/dedup	PASS WITH LOW RISKS	None	Minor profile construction duplication accepted.
docs	PASS AFTER FIXES	Fixed	Public/operator behavior docs updated and passed rereview.
docs rereview	PASS	None	Confirmed scoped docs and loop state.
test delta	PASS WITH LOW RISKS	None	Role-gate and refresh coverage requested.
test-delta final rereview	PASS	None	Confirmed test gaps fixed.

External Review

No external PR review has been run for this local chunk yet. CodeRabbit and
GitHub Actions should run after the PR is opened.

Remaining Risks

• Small duplication remains between worker/reviewer profile construction. It is
  not worth abstracting until another profile path appears.
• Post-submit policy derivation is still future work and intentionally not part
  of this chunk.

Human Review Focus

• Confirm the worker profile endpoint is the right product boundary for
  authenticated workers before claim.
• Confirm failed pre-submit audit evidence is useful without confusing it with a
  product review decision.
• Confirm active-guide checker summary exposes enough operator context while
  keeping compiled bundles private.

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.

Summary by CodeRabbit

• New Features

  • Workers can now create or refresh their own profile before claiming ready tasks.
  • Guide creation now supports attaching source-snapshot details.
  • Active-guide responses now expose checker names and configuration details.

• Bug Fixes

  • Duplicate guide versions now return a clear conflict response.
  • Failed pre-submit checks now record a durable audit event instead of silently stopping.
  • Skill tags are normalized and validated more strictly, helping prevent bad profile data.

• Documentation

  • Updated setup, policy, and architecture docs to match the new pre-submit and worker-profile behavior.

[coderabbitai]

Warning

Review limit reached

@Abiorh001, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 8 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b879c747-4b72-4412-8bd4-53f0608d7969

📥 Commits

Reviewing files that changed from the base of the PR and between 727f325 and cc78f2a.

📒 Files selected for processing (8)

• .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-10-external-review-response.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-10-internal-review-evidence.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-10-pr-trust-bundle.md
• backend/app/modules/tasks/router.py
• backend/tests/test_tasks.py
• docs/spec_chunk_4_task_queue_assignment.md

📝 Walkthrough

Walkthrough

This PR hardens pre-submit setup for the Terminal Benchmark API drill (WS-POL-001-10): it adds guide version conflict handling and optional source snapshots to guide creation, exposes checker names/configs on active-guide responses, introduces a worker profile upsert endpoint gating task claiming, and writes audit evidence on pre-submit checker failures. Documentation and agent-loop tracking files are updated accordingly.

Changes

Backend Behavior Changes

Layer / File(s)	Summary
Guide version conflict and source snapshot handling backend/app/modules/projects/schemas.py, backend/app/modules/projects/service.py, backend/tests/test_projects.py	Adds GuideVersionConflict (409) raised on duplicate guide version via IntegrityError handling, an optional source_snapshot field on guide creation, conditional snapshot creation/enqueueing, and tests for duplicate versions and snapshot-derived agent material.
Active-guide checker policy exposure backend/app/modules/projects/schemas.py, backend/tests/test_projects.py	Adds checker_names and checker_configs to PreSubmitCheckerPolicySummaryResponse and updates tests to assert their presence.
Worker profile API endpoint backend/app/modules/tasks/schemas.py, backend/app/modules/tasks/router.py, backend/app/modules/tasks/service.py, backend/tests/test_tasks.py, docs/spec_chunk_4_task_queue_assignment.md	Introduces WorkerProfileUpsertRequest/WorkerProfileResponse with skill-tag normalization, a new POST /workers/me/profile route, TaskService.ensure_worker_profile, and tests covering profile creation before claiming, validation, and role-based authorization.
Pre-submit failure audit evidence backend/app/modules/tasks/service.py, backend/tests/test_tasks.py, docs/architecture_data_model.md, docs/architecture_lockdown.md, docs/decision_0011_submission_artifact_policy_drives_pre_submit.md	Writes a pre_submission_check_failed task audit event with structured checker details before raising PreSubmissionCheckerFailed, with tests and docs confirming the new audit evidence without a created submission.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Agent-Loop Process Tracking Documents

Layer / File(s)	Summary
Loop state and initiative status updates .agent-loop/LOOP_STATE.md, .agent-loop/initiatives/.../STATUS.md	Updates current state, operating rule, review history, active chunk, and chunk status/blockers to reflect progression from WS-POL-001-09 to WS-POL-001-10.
Chunk spec, internal review evidence, and trust bundle .agent-loop/initiatives/.../chunks/WS-POL-001-10-pre-submit-live-drill-hardening.md, .agent-loop/initiatives/.../reviews/WS-POL-001-10-internal-review-evidence.md, .agent-loop/initiatives/.../reviews/WS-POL-001-10-pr-trust-bundle.md	Adds the chunk specification (scope, acceptance criteria, verification commands, stop conditions) and review documents recording internal review outcomes, test results, and merge ownership rules.

Possibly related PRs

• Flow-Research/workstream#7: Builds on the project-guide foundation extended here in ProjectGuideCreate/create_guide.
• Flow-Research/workstream#9: Extends worker profile infrastructure with the new /workers/me/profile endpoint and ensure_worker_profile.
• Flow-Research/workstream#10: Related work in TaskService.create_submission around the same pre-submit checker gating path.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: hardening pre-submit live drill flows.
Description check	✅ Passed	The description is mostly complete and covers the required chunk, scope, evidence, tests, and reviewer sections, though template headings are not fully mirrored.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-pol-001-10-pre-submit-hardening

---

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]

Actionable comments posted: 3

🤖 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.

Inline comments:
In
@.agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-10-internal-review-evidence.md:
- Around line 55-67: The test delta reviewer row is missing its own
checker-required metadata, so `scripts/check_internal_review_evidence.py` cannot
validate it from the row alone. Update the `test delta` entry in the internal
review evidence table to include the required `reviewed code sha` and `reviewer
run ids` fields directly, following the same canonical structure used by the
other reviewer rows.

In `@backend/app/modules/tasks/router.py`:
- Around line 84-102: The ensure_worker_profile endpoint is excluding nullable
fields from the response, which breaks the declared contract for
WorkerProfileResponse. Remove response_model_exclude_none from the router.post
decorator on ensure_worker_profile so WorkerProfileResponse.display_name and
email are still serialized even when they are None, keeping the response shape
consistent for clients.

In `@docs/spec_chunk_4_task_queue_assignment.md`:
- Around line 122-124: The endpoint inventory is incomplete because POST
/api/v1/workers/me/profile is documented in Security/Auth but missing from API
Impact > New endpoints. Update the New endpoints list in this spec to include
POST /api/v1/workers/me/profile, keeping the wording aligned with the existing
endpoint entries and the Security/Auth description so the two sections match.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b62b62ad-d429-4596-8226-8d3604737339

📥 Commits

Reviewing files that changed from the base of the PR and between 8a524de and 727f325.

📒 Files selected for processing (16)

• .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/chunks/WS-POL-001-10-pre-submit-live-drill-hardening.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-10-internal-review-evidence.md
• .agent-loop/initiatives/WS-POL-001-submission-artifact-policy-foundation/reviews/WS-POL-001-10-pr-trust-bundle.md
• backend/app/modules/projects/schemas.py
• backend/app/modules/projects/service.py
• backend/app/modules/tasks/router.py
• backend/app/modules/tasks/schemas.py
• backend/app/modules/tasks/service.py
• backend/tests/test_projects.py
• backend/tests/test_tasks.py
• docs/architecture_data_model.md
• docs/architecture_lockdown.md
• docs/decision_0011_submission_artifact_policy_drives_pre_submit.md
• docs/spec_chunk_4_task_queue_assignment.md