kandev/docs/plans/task-create-initial-turn-start/task-01-initial-create-prompt.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
01-initial-create-prompt	Admit the initial creation prompt through turn-start	done	1		plan.md	REQ-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-004 REQ-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-006	AC-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-004.1 AC-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-004.2 AC-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-004.3 AC-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-006.1 AC-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-006.2 AC-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-006.3 AC-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-006.4 AC-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-006.5 AC-TASKS-WORKFLOW-STEP-AGENT-START-OWNERSHIP-006.6	../../specs/tasks/system-design/workflow-step-agent-start-ownership.md

Task 01: Admit the initial creation prompt through turn-start

Summary

Connect immediate explicit-step creation to the existing user-message transition boundary. Keep one prompt owner through session replacement, WIP admission, and passthrough running notifications.

In scope

• Add the private create-prompt marker before destination inference in REST and MCP adapters.
• Implement shared prepared-session admission in task_create_prompt.go and route marked launch requests through it.
• Process the trigger before composition; reload destination state, honor WIP queuing, and retain initial prompt metadata.
• Bind passthrough suppression to one initial execution/turn; retire it on completion, failure, cancellation, or replacement.
• Add all tests in the plan's matrix with TDD. Prove the primary regression fails before implementation.
• Update the on_turn_start explanation in docs/public/workflow-tips.md after behavior works. This explanation page must distinguish initial explicit-step input from automatic workflow-entry prompts.

Out of scope

Dependency-deferred creates, attachment-only creates, historical repair, provider changes, UI changes, and new public launch fields. Do not change the original context-reset or asynchronous prompt-preservation packages.

Acceptance

1. Both creation adapters select the corrected path only for eligible original requests, after existing settlement and admission gates.
2. The first prompt-bearing dispatch observes the destination step/session/settings and one message; queue replay and running notifications do not trigger another transition.
3. All negative controls retain their behavior, failures prevent stale dispatch, and the documented verification commands pass.

Implementation sequence

1. Add TestInitialCreatePrompt_TransitionsBeforeDispatch using the existing scheduler, SQLite, workflow engine, and mock agent fixtures.
2. Observe its failure with a pinned Backlog task and a move-to-Spec action.
3. Add shared admission and transport wiring; avoid duplicating transition logic in handlers.
4. Add the queue, passthrough, profile-switch, failure, replacement, and non-eligible controls from the plan.
5. Add TestWorkflowE2E_InitialCreatePrompt with a dispatch observer and completion transition.
6. Update public documentation and run every verification command.

Verification

Run from the repository root. The first command selects the new regression family during TDD. The package command covers all modified Go suites and their existing creation, queue, and lifecycle regressions.

(cd apps/backend && go test -tags fts5 ./internal/orchestrator -run 'TestInitialCreatePrompt_|TestWorkflowE2E_InitialCreatePrompt' -count=1 -v)
(cd apps/backend && go test -tags fts5 -race ./internal/orchestrator ./internal/task/handlers ./internal/mcp/handlers)
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.test.py
python3 scripts/lint-spec-files.py --all
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
git diff --check

Files likely touched

• apps/backend/internal/orchestrator/session_launch.go
• apps/backend/internal/orchestrator/task_create_prompt.go (new)
• apps/backend/internal/orchestrator/task_create_prompt_test.go (new)
• apps/backend/internal/orchestrator/task_operations.go
• apps/backend/internal/orchestrator/event_handlers_workflow.go
• apps/backend/internal/orchestrator/event_handlers_agent.go
• apps/backend/internal/orchestrator/event_handlers_queue_general_test.go
• apps/backend/internal/orchestrator/event_handlers_passthrough_lifecycle_test.go
• apps/backend/internal/orchestrator/workflow_e2e_test.go
• apps/backend/internal/task/handlers/task_http_handlers.go
• apps/backend/internal/task/handlers/task_http_handlers_test.go
• apps/backend/internal/mcp/handlers/handlers.go
• apps/backend/internal/mcp/handlers/handlers_test.go
• apps/backend/internal/mcp/handlers/create_task_external_id_test.go
• apps/backend/internal/mcp/handlers/destination_step_test.go
• docs/public/workflow-tips.md
• This plan and work order, for implementation results.

Dependencies

None. Execute in the primary session after a later implementation request.

Risks

Do not hold the cancellation guard across another call that acquires it. Do not infer explicit selection from the resolved MCP destination or the AutoStart flag. Do not bypass launch ceilings, first-message admission, attachment claims, or session replacement checks. If helpers hide an engine failure, return that failure before creation dispatch without changing unrelated callers' behavior. Retain existing step-prompt composition; do not introduce a new prompt concatenation policy.

Parallelism

sequential

Inputs

• Plan and diagnostic evidence.
• Requirements 004 and 006.
• Initial creation prompt admission.
• wsAddMessage in message_handlers.go: transition, resulting session, queue admission, and composition ordering.
• TestStartCreatedSession_WrapsFirstPromptWithKandevSystemBlock for prepared-launch fixtures.
• TestExecuteQueuedMessage_SkipsOnTurnStartWhenAlreadyProcessed for queue trigger ownership.
• Existing REST settlement and MCP external-ID tests for forbidden early dispatch.

Results

Completed on 2026-09-19.

• Added server-side eligibility provenance for explicit, prompt-bearing immediate creation in the REST and MCP adapters.
• Routed marked creation starts through the shared turn-start admission boundary before prompt composition and provider dispatch.
• Preserved destination session/profile resolution, WIP queueing, attachment and prompt handling, and one-message ownership.
• Added scoped passthrough evidence for direct and queued initial turns. Running, completion, failure, stop, replacement, and dispatch-failure paths retire the evidence.
• Persisted strict-admission and queue-insertion failures through guarded launch-error ownership. Superseded sources and unrelated successors are left unchanged, while a replacement that owns the changed workflow step receives the error.
• Updated the public on_turn_start workflow guidance.

Verification passed:

go test -tags fts5 ./internal/orchestrator -count=1
go test -tags fts5 ./internal/task/handlers ./internal/mcp/handlers -count=1
go test -tags fts5 -race ./internal/orchestrator -run '^(TestInitialCreatePrompt_|TestWorkflowE2E_InitialCreatePrompt$)' -count=1
go test -tags fts5 -race ./internal/orchestrator ./internal/task/handlers ./internal/mcp/handlers -count=1
make -C apps/backend build
make -C apps/backend lint
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.test.py
python3 scripts/lint-spec-files.py --all
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
git diff --check

The temporary diagnostic reproduction was removed. No schema, provider protocol, or UI changes were required.