feat(workflow-executor): add AI-assisted and Full AI execution to the guidance step (PRD-148 pattern, PRD-18)

[Scra3]

What

Adds the 3-way Execution mode (Manual / AI-assisted / Full AI) to the Guidance step. Part of PRD-18 — 3-PR set (executor + `ForestAdmin/forestadmin-server` orchestrator + `ForestAdmin/forestadmin` editor).

• Manual — human types + submits (unchanged); AI never called.
• AI-assisted (automated-with-confirmation) — AI pre-fills the free-text response from the step prompt + workflow context; persisted as pendingData.userInput with an aiGenerated flag (drives the front "AI" badge); the human edits/submits.
• Full AI (fully-automated) — AI writes and submits automatically (executionResult.userInput + generatedByAi); the response becomes a variable reusable by downstream steps.

Degrade / resilience (product-confirmed): on AI failure/timeout, or an empty draft, the step degrades to Manual (empty field, pendingData: {}) — the run never fails, the step never auto-skips. Full AI always submits on a valid draft (no low-confidence degrade — a text generator, unlike Load Related Record). The AI is never re-run on re-dispatch of the same (runId, stepIndex).

withAiAssist + logAiDegrade are hoisted from LoadRelatedRecordStepExecutor into BaseStepExecutor (2nd consumer); load-related behavior is unchanged.

Tests

Full suite green (1412). Added: Manual never calls AI; submit path never calls AI; AI-assisted pre-fill + badge flag + re-dispatch no-regen + degrade (AI failure / empty draft) + no-retry-after-degrade; Full AI submit + replay + degrade; schema (3-way, no .catch, rejects unknown); mapper (3 values + default manual). Load-related suite unchanged (hoist is behavior-neutral).

Relates to PRD-18.

🤖 Generated with Claude Code

Note

Add AI-assisted and fully automated execution modes to guidance step executor

• GuidanceStepExecutor now supports three execution modes: Manual returns awaiting-input unchanged; AutomatedWithConfirmation uses an AI tool-call to draft a response, persists it as pendingData, and pauses for user confirmation; FullyAutomated persists the AI response as executionResult and completes.
• AI calls are wrapped via a new BaseStepExecutor.withAiAssist helper (moved up from LoadRelatedRecordStepExecutor) that normalizes failures to AiAssistUnavailableError; empty or failed AI drafts degrade to manual by persisting an empty pendingData.
• GuidanceStepDefinitionSchema now accepts all three execution modes explicitly and rejects unknown values; missing executionType defaults to Manual.
• GuidanceStepExecutionData gains optional aiGenerated/generatedByAi flags and supports an empty pendingData object to signal degrade state.
• Risk: guidance steps with invalid executionType values that were previously coerced to Manual will now be rejected outright.

📊 Macroscope summarized 720c832. 6 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[linear-code]

PRD-148

PRD-18

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 8): doExecute	1

[qltysh]

Coverage Impact

⬆️ Merging this pull request will increase total coverage on main by 0.01%.

Modified Files with Diff Coverage (3)

Rating	File	% Diff	Uncovered Line #s
	packages/workflow-executor/src/executors/base-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.