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

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:

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

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