kandev/docs/plans/task-completion/task-02-portable-contracts.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
02-portable-contracts	Carry portable completion settings	done	2	01-persistence	plan.md	REQ-TASKS-COMPLETION-001	AC-TASKS-COMPLETION-001.4 AC-TASKS-COMPLETION-001.7 AC-TASKS-COMPLETION-001.8	../../specs/tasks/system-design/task-completion.md

Task 02: Carry portable completion settings

Summary

Expose the persisted setting through all workflow creation and transport boundaries. Make version-1 compatibility conversion explicit while current exports use version 2.

In scope

• Carry the field through models/StepDefinition, loader, task DTO, workflow controller, REST/WS handlers, stepevents, and MCP schemas/handlers. Omitted PATCH preserves; explicit false disables; null is rejected.
• Normalize version-1 omitted fields at whole-workflow import/sync boundaries using the legacy terminal predicate. Version 2 requires explicit booleans; current exports include false and do not omit it.
• Update template conversion and each built-in YAML with explicit values. Update sync equality, invalid-file handling, embedded config-context instructions, and payload parity tests.

Out of scope

Do not change runtime completion authority or frontend editing yet.

Acceptance

• Create/update/list/boot/event/MCP projections agree, including omitted update and explicit false.
• Both portable versions import correctly; export produces version 2. Sync create/update/no-op preserves explicit false and reports invalid version-2 input without destructive reconciliation.
• Templates and new workspace bootstrap preserve each built-in workflow's previous completion intent.

TDD entry

Add TestCompletionPortableVersions and TestCompletionSyncPreservesFalse in workflow model/service completion_portable_test.go files. Start with a version-1 omitted field on a final Done and a current export containing explicit false; assert the resulting behavior, not just structure.

Verification

Run from apps/backend/. PostgreSQL-dependent cases use an isolated KANDEV_TEST_POSTGRES_DSN; never point tests at the reported installation.

rtk go test -race ./config/workflows ./internal/workflow/models ./internal/workflow/controller ./internal/workflow/handlers ./internal/workflow/service ./internal/workflow/stepevents ./internal/task/dto ./internal/workflowsync -count=1
rtk go test -race ./internal/mcp/handlers ./internal/mcp/server -run 'Test.*(Workflow|Step|Config)' -count=1
rtk go test -race ./internal/task/repository/sqlite -run 'Test.*(Builtin|Workflow|Bootstrap)' -count=1

Files likely touched

• apps/backend/config/workflows/loader.go
• apps/backend/config/workflows/*.yml
• apps/backend/config/prompts/config-context.md
• apps/backend/internal/workflow/models/export.go
• apps/backend/internal/workflow/models/completion_portable_test.go (new)
• apps/backend/internal/workflow/controller/controller.go
• apps/backend/internal/workflow/service/service.go
• apps/backend/internal/workflow/service/sync_apply.go
• apps/backend/internal/workflow/service/completion_portable_test.go (new)
• apps/backend/internal/workflow/stepevents/stepevents.go
• apps/backend/internal/task/dto/dto.go
• apps/backend/internal/task/dto/converters.go
• apps/backend/internal/mcp/handlers/config_workflow_handlers.go
• apps/backend/internal/mcp/server/config_handlers.go
• apps/backend/internal/workflowsync (portable decode callers)

Dependencies

Complete 01-persistence first.

Risks

A bool alone cannot distinguish absent from explicit false/null at compatibility boundaries. Final position establishes eligibility only; it must never default the setting to true. Retain inactive non-final values across round trips. Refresh affected test fixtures using ExportVersion so new required fields do not become false-positive parsing failures.

Parallelism

sequential

Inputs

• Requirements, criteria in frontmatter.
• System design.
• Plan, confirmed source trace and existing reproduction tests.
• Nearby Go repository/handler tests supply fixture conventions.
• Follow /tdd in the primary session.

Results

Done. The persisted setting now crosses the backend model, loader, service, controller, MCP, DTO, step-event, frontend API, and workflow-draft boundaries. Version 2 exports explicit booleans; version 1 imports normalize omitted values at the boundary. Sync preserves explicit false values and invalid version 2 input is rejected before reconciliation.

Verification:

• rtk go test -race ./config/workflows ./internal/workflow/models ./internal/workflow/controller ./internal/workflow/service ./internal/workflow/stepevents ./internal/task/dto ./internal/workflowsync -count=1 (426 passed)
• rtk go test -race ./internal/mcp/handlers ./internal/mcp/server -run 'Test.*(Workflow|Step|Config)' -count=1 (172 passed)
• rtk go test -race ./internal/task/repository/sqlite -run 'Test.*(Builtin|Workflow|Bootstrap)' -count=1 (65 passed)
• Targeted web contract and workflow-draft tests (31 passed), plus web typecheck.