ln-500-story-quality-gate

What this skill does

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

**Type:** L2 Coordinator
**Category:** 5XX Quality

# Story Quality Gate

Runtime-backed gate coordinator. Owns fast-track routing, quality/test summaries, final Story verdict, and branch finalization.

## Inputs

| Input | Required | Source | Description |
|-------|----------|--------|-------------|
| `storyId` | Yes | args, git branch, kanban, user | Story to process |

**Resolution:** Story Resolution Chain.  
**Status filter:** To Review

## Purpose & Scope

- Invoke `ln-510-quality-coordinator`
- Invoke `ln-520-test-planner` when needed
- Wait deterministically for test-task readiness
- Calculate gate verdict: `PASS | CONCERNS | FAIL | WAIVED`
- Move Story to `Done` only on passing outcomes
- Persist resumable gate runtime in `.hex-skills/story-gate/runtime/`

## 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_gate_runtime_contract.md`, `references/coordinator_summary_contract.md`, `references/loop_health_contract.md`
**MANDATORY READ:** Load `references/git_worktree_fallback.md`
**MANDATORY READ:** Load `references/minimum_quality_checks.md`

Runtime CLI:

```bash
node references/scripts/story-gate-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-gate/manifest.json
node references/scripts/story-gate-runtime/cli.mjs status
node references/scripts/story-gate-runtime/cli.mjs record-quality --payload '{...}'
node references/scripts/story-gate-runtime/cli.mjs record-test-status --payload '{...}'
node references/scripts/story-gate-runtime/cli.mjs record-stage-summary --story {storyId} --payload '{...}'
node references/scripts/story-gate-runtime/cli.mjs checkpoint --phase PHASE_6_VERDICT --payload '{...}'
node references/scripts/story-gate-runtime/cli.mjs advance --to PHASE_7_FINALIZATION
```

## 4-Level Gate Model

| Verdict | Meaning | Action |
|---------|---------|--------|
| `PASS` | All checks passed | Story -> `Done` |
| `CONCERNS` | Minor issues, accepted risk | Story -> `Done` with comment |
| `FAIL` | Blocking issues found | Create follow-up tasks; Story does not go to `Done` |
| `WAIVED` | User-approved exception | Story -> `Done` with waiver evidence |

## Workflow

### Phase 0: Config

1. Resolve `storyId` and `task_provider`.
2. Check for prior Stage 3 artifact at `.hex-skills/runtime-artifacts/runs/*/story-quality/{storyId}.json`:
   - If found with `verdict=FAIL`, load `payload.metadata.rework_hint` as `previous_cycle` context.
   - Record `cycle_number` (1-based, incremented from prior artifact count).
3. Build gate manifest:
   - `story_id`
   - `task_provider`
   - `project_root`
   - `worktree_dir`
   - `branch`
   - `fast_track_policy`
   - `nfr_policy`
   - `test_task_policy`
   - `previous_cycle` (null or loaded rework_hint)
   - `cycle_number`
4. Start runtime and checkpoint `PHASE_0_CONFIG`.

### Phase 1: Discovery

1. Load Story metadata and child task metadata.
2. Detect existing test task and its current status.
3. Capture readiness inputs if available from upstream pipeline.
4. Checkpoint `PHASE_1_DISCOVERY`.

### Phase 2: Fast-Track

1. Determine `fast_track=true` only when readiness explicitly allows it.
2. Checkpoint `PHASE_2_FAST_TRACK` with:
   - `fast_track`
   - gate scope summary

### Phase 3: Quality Checks

1. Compute:
   - `childRunId = {parent_run_id}--ln-510--{storyId}`
   - `childSummaryArtifactPath = .hex-skills/runtime-artifacts/runs/{parent_run_id}/story-quality/{storyId}.json`
2. Materialize child manifest and start child coordinator runtime:
   - `node references/scripts/quality-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-gate/ln-510--{storyId}_manifest.json --run-id {childRunId}`
3. Checkpoint `PHASE_3_QUALITY_CHECKS` with:
   - `child_run.worker=ln-510`
   - `child_run.run_id={childRunId}`
   - `child_run.summary_artifact_path={childSummaryArtifactPath}`
   - `child_run.phase_context=quality_checks`
4. Invoke `ln-510-quality-coordinator` with managed transport inputs:
   - full mode: `Skill(skill: "ln-510-quality-coordinator", args: "{storyId} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")`
   - fast-track: `Skill(skill: "ln-510-quality-coordinator", args: "{storyId} --fast-track --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")`
   - full mode with prior cycle: append `--previous-cycle-focus "{blocking_categories}"` when `previous_cycle` is not null
5. Read child `story-quality` artifact only, then `record-quality`.
6. Before another quality/rework cycle, compare FAIL evidence against prior cycle:
   - progress = new quality artifact, new fix tasks, code delta, status delta, or changed blocking category
   - same FAIL with no new evidence = record loop health and pause before another rework cycle
7. Checkpoint `PHASE_3_QUALITY_CHECKS` with the recorded quality summary.
8. If the quality summary already implies hard FAIL, you may jump directly to `PHASE_6_VERDICT`.

### Phase 4: Test Planning

1. Decide whether planning is needed:
   - no test task -> invoke `ln-520`
   - fast-track -> invoke simplified `ln-520`
   - test task already exists and is terminal (`Done | SKIPPED | VERIFIED`) -> checkpoint as reused
2. When invoking `ln-520`, compute:
   - `childRunId = {parent_run_id}--ln-520--{storyId}`
   - `childSummaryArtifactPath = .hex-skills/runtime-artifacts/runs/{parent_run_id}/story-tests/{storyId}.json`
3. Materialize child manifest and start child coordinator runtime:
   - `node references/scripts/test-planning-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-gate/ln-520--{storyId}_manifest.json --run-id {childRunId}`
4. Checkpoint `PHASE_4_TEST_PLANNING` with:
   - `child_run.worker=ln-520`
   - `child_run.run_id={childRunId}`
   - `child_run.summary_artifact_path={childSummaryArtifactPath}`
   - `child_run.phase_context=test_planning`
5. Invoke `ln-520-test-planner` with managed transport inputs:
   - normal mode: `Skill(skill: "ln-520-test-planner", args: "{storyId} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")`
   - simplified mode: `Skill(skill: "ln-520-test-planner", args: "{storyId} --simplified --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")`
6. Read child `story-tests` artifact only, then `record-test-status`.
7. Checkpoint `PHASE_4_TEST_PLANNING`.

### Phase 5: Test Verification

1. If test task exists but is not `Done`, pause runtime:
   - `phase = PAUSED`
   - `resume_action = wait for test task completion`
2. When resumed, verify:
   - test task terminal status is `Done`, `SKIPPED`, or `VERIFIED`
   - coverage summary exists
   - planned scenarios and Story AC coverage are machine-readable
3. Checkpoint `PHASE_5_TEST_VERIFICATION` with:
   - `test_task_status`
   - verification result

### Phase 6: Verdict

1. Calculate `quality_score`.
2. Evaluate NFR validation:
   - full gate: security, performance, reliability, maintainability
   - fast-track: security mandatory, others may downgrade to concerns-only scope
3. **End-to-End Scenario Completeness Walkthrough:** For each AC where an actor (user, bot, scheduler, handler, pipeline) must invoke or consume a mechanism, trace all 5 segments of the interaction path:
   - **(1) Actor trigger** — what initiates the scenario (user sends message, timer fires, webhook arrives, event is enqueued)
   - **(2) Entry point** — the named mechanism (MCP tool, API endpoint, CLI command, UI component, chat handler, config file, cron handler)
   - **(3) Discovery** — how the actor's system finds/loads the mechanism at runtime (config registration, route mounting, plugin loading, system prompt, environment variable)
   - **(4) Usage context** — what the actor's system needs