ln-400-story-executor

What this skill does

> **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:

```bash
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:
   - `story_id`
   - `task_provider`
   - `project_root`
   - planned `worktree_dir`
   - branch name
   - `parallel_group_policy`
   - `status_transition_policy`
4. Start runtime and checkpoint `PHASE_0_CONFIG`.

### Phase 1: Discovery

1. Resolve Story title and current Story status.
2. Load child task metadata only:
   - Use the configured tracker provider's `listTasksByStory(storyId)` operation (transport per `references/provider_file.md, references/provider_github.md, references/provider_linear.md`).
3. Build `processable_counts` for:
   - `to_review`
   - `to_rework`
   - `todo`
4. 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:
   - `worktree_ready`
   - `worktree_dir`
   - `branch`
5. 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:
   - tasks with `**Parallel Group:** {N}` may run as one group
   - 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:
   - Action: compare current worker output with previous task loop health.
   - Key point: retry only when new artifact, new `ln-402` summary, task status delta, `files_changed` delta, or scenario improvement exists.
   - Why: repeated identical worker failures create retry storms without adding evidence.
   - Evidence: `record-loop-health --scope task --scope-id {taskId}` result.
   - Exception: if `pause.pause=true`, stop and surface `paused_reason`.
   - Automation/guard: story-execution runtime pauses after same-error/no-progress threshold.
8. When review is required, repeat the same runtime-backed sequence for `ln-402`.
9. 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`.
10. Record worker artifacts with `record-worker`.
11. Checkpoint `PHASE_4_TASK_EXECUTION`.
12. 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, reconstr