feat(workflow-executor): add guidance step type (PRD-272)

[Scra3]

Summary

Add a new "guidance" step type for manual user input without AI.

Flow

1. Front displays instruction + text input to user
2. User types and clicks Submit
3. Front triggers POST /runs/:runId/trigger with { pendingData: { userInput: "..." } }
4. Executor saves input in RunStore and returns success
5. Subsequent AI steps see the input in their context

Changes

• StepType.Guidance + GuidanceStepDefinition
• GuidanceStepExecutor: reads userInput from store, saves executionResult, returns success
• patchPendingData auto-creates execution for never-polled steps (scoped to Guidance only)
• Zod validator: { userInput: z.string().min(1) }
• Step summary formatter for AI context in subsequent steps

Test plan

• 437 tests pass
• TypeScript compiles
• Lint clean
• GuidanceStepExecutor: success path, no execution error, no userInput error
• patchPendingData auto-creation for guidance
• Zod validation rejects empty userInput
• Step formatter outputs correct summary

fixes PRD-272

🤖 Generated with Claude Code

Note

Add guidance step type to workflow executor

• Introduces GuidanceStepExecutor, a new step type that records user-provided userInput from incomingPendingData and returns a success outcome without any AI calls.
• Moves pending data validation and persistence from Runner.patchPendingData into individual executors via a new BaseStepExecutor.patchAndReloadPendingData method, giving each executor control over its own pending data schema.
• Extends StepExecutorFactory to construct GuidanceStepExecutor for StepType.Guidance and passes incomingPendingData through the execution context.
• Adds a formatGuidance formatter to StepExecutionFormatters so guidance results render a summary line quoting the user input.
• Behavioral Change: the /runs/:runId/trigger endpoint no longer returns 400/404 for invalid or missing pending data; such errors are now handled inside executors and fall through to a 500 if unhandled.

^{Macroscope summarized 26b9c2f.}

[linear]

PRD-272 Guidance task step: save user input via trigger without prior polling

[qltysh]

5 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 8): create	3
qlty	Structure	Function with many parameters (count = 4): create	1
qlty	Structure	Function with high complexity (count = 15): build	1

[qltysh]

Coverage Impact

⬇️ Merging this pull request will decrease total coverage on feat/prd-214-setup-workflow-executor-package by 0.02%.

Modified Files with Diff Coverage (14)

Rating	File	% Diff	Uncovered Line #s
	packages/workflow-executor/src/runner.ts	100.0%
	packages/workflow-executor/src/executors/step-executor-factory.ts	100.0%
	...ow-executor/src/executors/load-related-record-step-executor.ts	100.0%
	...orkflow-executor/src/executors/summary/step-summary-builder.ts	100.0%
	packages/workflow-executor/src/types/step-outcome.ts	100.0%
	packages/workflow-executor/src/types/step-definition.ts	100.0%
	packages/workflow-executor/src/executors/base-step-executor.ts	100.0%
	packages/workflow-executor/src/http/executor-http-server.ts	100.0%
	...workflow-executor/src/executors/update-record-step-executor.ts	100.0%
	...-executor/src/executors/trigger-record-action-step-executor.ts	100.0%
	packages/workflow-executor/src/index.ts	100.0%
	packages/workflow-executor/src/executors/mcp-step-executor.ts	100.0%
	...ow-executor/src/executors/summary/step-execution-formatters.ts	100.0%
	...ages/workflow-executor/src/executors/guidance-step-executor.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[macroscopeapp]

🟡 Medium executors/base-step-executor.ts:127

patchAndReloadPendingData uses a non-null assertion (!) on patchBodySchemas[execution.type], but patchBodySchemas is a Partial that only includes schemas for specific step types. When the method is called with an execution whose type is not in that set (e.g., condition or read-record), schema becomes undefined and schema.safeParse(pendingData) throws a runtime error. Consider validating that the schema exists and throwing a StepStateError when the step type does not support pending data patches.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/workflow-executor/src/executors/base-step-executor.ts around line 127:

`patchAndReloadPendingData` uses a non-null assertion (`!`) on `patchBodySchemas[execution.type]`, but `patchBodySchemas` is a `Partial` that only includes schemas for specific step types. When the method is called with an execution whose type is not in that set (e.g., `condition` or `read-record`), `schema` becomes `undefined` and `schema.safeParse(pendingData)` throws a runtime error. Consider validating that the schema exists and throwing a `StepStateError` when the step type does not support pending data patches.

Evidence trail:
- packages/workflow-executor/src/executors/base-step-executor.ts lines 127-140 (REVIEWED_COMMIT): `patchAndReloadPendingData` method with `patchBodySchemas[execution.type]!` at line 134
- packages/workflow-executor/src/pending-data-validators.ts lines 5-43 (REVIEWED_COMMIT): `patchBodySchemas` defined as `Partial<Record<StepExecutionData['type'], z.ZodTypeAny>>` with only 5 step types having schemas
- packages/workflow-executor/src/types/step-execution-data.ts lines 140-150 (REVIEWED_COMMIT): `StepExecutionData` union type includes 8 types, 3 of which (`condition`, `read-record`, `record`) have no schema in `patchBodySchemas`
- packages/workflow-executor/src/executors/guidance-step-executor.ts lines 17-20 (REVIEWED_COMMIT): Shows correct pattern with explicit `if (!schema)` check before use