ln-400-story-executor

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

Type: L2 Coordinator Category: 4XX Execution

Story Execution Orchestrator

Runtime-backed coordinator for Story execution. Owns task ordering, worktree lifecycle, task/group checkpoints, and the final Story transition to To Review.

Inputs

| Input | Required | Source | Description | |-------|----------|--------|-------------| | storyId | Yes | args, git branch, kanban, user | Story to process | | --rework-focus | No | ln-1000 | Comma-separated blocking categories from prior quality gate FAIL |

Resolution: Story Resolution Chain. Status filter: Todo, In Progress, To Rework, To Review

Purpose & Scope

• Load Story and task metadata once per loop
• Execute in order: To Review -> To Rework -> Todo
• Launch Todo parallel groups only when explicitly marked
• Force immediate review after every executor/rework step
• Persist resumable runtime state in .hex-skills/story-execution/runtime/
• Move Story only to To Review; never to Done

Runtime Contract

MANDATORY READ: Load references/environment_state_contract.md, references/storage_mode_detection.md, references/input_resolution_pattern.md MANDATORY READ: Load references/coordinator_runtime_contract.md, references/story_execution_runtime_contract.md, references/coordinator_summary_contract.md, references/loop_health_contract.md MANDATORY READ: Load references/git_worktree_fallback.md — use the Story execution row

Runtime CLI:

node references/scripts/story-execution-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-execution/manifest.json
node references/scripts/story-execution-runtime/cli.mjs status
node references/scripts/story-execution-runtime/cli.mjs checkpoint --phase PHASE_3_SELECT_WORK --payload '{...}'
node references/scripts/story-execution-runtime/cli.mjs record-worker --task-id {taskId} --payload '{...}'
node references/scripts/story-execution-runtime/cli.mjs record-group --group-id {groupId} --payload '{...}'
node references/scripts/story-execution-runtime/cli.mjs record-stage-summary --story {storyId} --payload '{...}'
node references/scripts/story-execution-runtime/cli.mjs record-loop-health --scope task --scope-id {taskId} --payload '{...}'
node references/scripts/story-execution-runtime/cli.mjs advance --to PHASE_4_TASK_EXECUTION

Workflow

Phase 0: Config

1. Resolve storyId.
2. Detect task_provider from task-management config.
3. Build execution manifest:
4. story_id
5. task_provider
6. project_root
7. planned worktree_dir
8. branch name
9. parallel_group_policy
10. status_transition_policy
11. Start runtime and checkpoint PHASE_0_CONFIG.

Phase 1: Discovery

1. Resolve Story title and current Story status.
2. Load child task metadata only:
3. Use the configured tracker provider's listTasksByStory(storyId) operation (transport per references/provider_file.md, references/provider_github.md, references/provider_linear.md).
4. Build processable_counts for:
5. to_review
6. to_rework
7. todo
8. Checkpoint PHASE_1_DISCOVERY.

Phase 2: Worktree Setup

1. Detect current branch.
2. If already inside feature/*, treat current directory as active worktree.
3. Otherwise create .hex-skills/worktrees/story-{identifier} and branch feature/{identifier}-{slug} per worktree fallback guide.
4. Checkpoint PHASE_2_WORKTREE_SETUP with:
5. worktree_ready
6. worktree_dir
7. branch
8. Advance only after worktree_ready=true.

Phase 3: Select Work

Selection order is deterministic:

1. Any To Review task first, sequentially
2. Then any To Rework task, sequentially
3. Then Todo tasks:
4. tasks with Parallel Group: {N} may run as one group
5. tasks without a group are single-task sequential units

Checkpoint PHASE_3_SELECT_WORK with:

• current_task_id or current_group_id
• fresh processable_counts

If all processable counts are zero, skip execution and advance to PHASE_7_STORY_TO_REVIEW.

When rework_focus is provided:

• Tasks whose title or AC keywords match any blocking_categories entry are selected first within the same priority tier.
• This does not override the To Review > To Rework > Todo ordering — it reorders within each tier.

Phase 4: Task Execution

Used for:

• To Review -> ln-402
• To Rework -> ln-403, then immediate ln-402
• single Todo test task -> ln-404, then immediate ln-402
• single Todo impl/refactor task -> ln-401, then immediate ln-402

Flow:

1. Compute executor childRunId = {parent_run_id}--{worker}--{taskId}.
2. Compute executor artifact path .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--{worker}.json.
3. Materialize executor manifest at .hex-skills/story-execution/{worker}--{taskId}_manifest.json.
4. Start task-worker-runtime and checkpoint executor child_run metadata before invocation.
5. Execute the worker through Agent or Skill with --run-id and --summary-artifact-path.
6. Read the executor summary artifact from .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--{worker}.json.
7. Record task loop health before retrying the same task/worker/error:
8. Action: compare current worker output with previous task loop health.
9. Key point: retry only when new artifact, new ln-402 summary, task status delta, files_changed delta, or scenario improvement exists.
10. Why: repeated identical worker failures create retry storms without adding evidence.
11. Evidence: record-loop-health --scope task --scope-id {taskId} result.
12. Exception: if pause.pause=true, stop and surface paused_reason.
13. Automation/guard: story-execution runtime pauses after same-error/no-progress threshold.
14. When review is required, repeat the same runtime-backed sequence for ln-402.
15. Read the latest ln-402 review summary artifact for the same task from .hex-skills/runtime-artifacts/runs/{parent_run_id}/task-status/{taskId}--ln-402.json.
16. Record worker artifacts with record-worker.
17. Checkpoint PHASE_4_TASK_EXECUTION.
18. Advance to PHASE_6_VERIFY_STATUSES.

Phase 5: Group Execution

Used only for Todo groups with more than one task.

1. For each task, compute worker-specific child runId, artifact path, and manifest path.
2. Start one task-worker-runtime per executor and checkpoint all child metadata before spawning Agents.
3. Spawn all group executors in parallel via Agent tool.
4. Wait for all executors to finish.
5. Read each executor summary artifact.
6. Start one ln-402 runtime per task, review each task sequentially, and read the latest review artifact for every task.
7. Record each worker artifact with record-worker, then record the group summary with record-group.
8. Checkpoint PHASE_5_GROUP_EXECUTION.
9. Advance to PHASE_6_VERIFY_STATUSES.

Phase 6: Verify Statuses

1. Re-read task metadata from source of truth.
2. Refresh processable_counts.
3. Validate that every task touched in this run has a latest ln-402 machine-readable summary.
4. If any worker leaves an unexpected transition, pause runtime.
5. If any task hits To Rework for the third consecutive time, pause runtime with escalation reason.
6. Checkpoint PHASE_6_VERIFY_STATUSES.
7. If processable work remains -> advance back to PHASE_3_SELECT_WORK.
8. If no processable work remains -> advance to PHASE_6B_SCENARIO_VALIDATION.

Scenario Validation

Runs once when all tasks are Done. Delegates to an external agent to trace the user scenario end-to-end against implemented code. The executor has completion bias after shepherding tasks through implementation — an external agent has no investment in the story being done.

1. Load the Story ACs and the traceability table (from .hex-skills/task-planning/{identifier}_traceability.md). If the traceability artifact is missing, reconstru