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-plannerwhen needed - Wait deterministically for test-task readiness
- Calculate gate verdict:
PASS | CONCERNS | FAIL | WAIVED - Move Story to
Doneonly 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
| 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
- Resolve
storyIdandtask_provider. - Check for prior Stage 3 artifact at
.hex-skills/runtime-artifacts/runs/*/story-quality/{storyId}.json:- If found with
verdict=FAIL, loadpayload.metadata.rework_hintasprevious_cyclecontext. - Record
cycle_number(1-based, incremented from prior artifact count).
- If found with
- Build gate manifest:
story_idtask_providerproject_rootworktree_dirbranchfast_track_policynfr_policytest_task_policyprevious_cycle(null or loaded rework_hint)cycle_number
- Start runtime and checkpoint
PHASE_0_CONFIG.
Phase 1: Discovery
- Load Story metadata and child task metadata.
- Detect existing test task and its current status.
- Capture readiness inputs if available from upstream pipeline.
- Checkpoint
PHASE_1_DISCOVERY.
Phase 2: Fast-Track
- Determine
fast_track=trueonly when readiness explicitly allows it. - Checkpoint
PHASE_2_FAST_TRACKwith:fast_track- gate scope summary
Phase 3: Quality Checks
- Compute:
childRunId = {parent_run_id}--ln-510--{storyId}childSummaryArtifactPath = .hex-skills/runtime-artifacts/runs/{parent_run_id}/story-quality/{storyId}.json
- 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}
- Checkpoint
PHASE_3_QUALITY_CHECKSwith:child_run.worker=ln-510child_run.run_id={childRunId}child_run.summary_artifact_path={childSummaryArtifactPath}child_run.phase_context=quality_checks
- Invoke
ln-510-quality-coordinatorwith 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}"whenprevious_cycleis not null
- full mode:
- Read child
story-qualityartifact only, thenrecord-quality. - 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
- Checkpoint
PHASE_3_QUALITY_CHECKSwith the recorded quality summary. - If the quality summary already implies hard FAIL, you may jump directly to
PHASE_6_VERDICT.
Phase 4: Test Planning
- 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
- no test task -> invoke
- 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
- 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}
- Checkpoint
PHASE_4_TEST_PLANNINGwith:child_run.worker=ln-520child_run.run_id={childRunId}child_run.summary_artifact_path={childSummaryArtifactPath}child_run.phase_context=test_planning
- Invoke
ln-520-test-plannerwith 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}")
- normal mode:
- Read child
story-testsartifact only, thenrecord-test-status. - Checkpoint
PHASE_4_TEST_PLANNING.
Phase 5: Test Verification
- If test task exists but is not
Done, pause runtime:phase = PAUSEDresume_action = wait for test task completion
- When resumed, verify:
- test task terminal status is
Done,SKIPPED, orVERIFIED - coverage summary exists
- planned scenarios and Story AC coverage are machine-readable
- test task terminal status is
- Checkpoint
PHASE_5_TEST_VERIFICATIONwith:test_task_status- verification result
Phase 6: Verdict
- Calculate
quality_score. - Evaluate NFR validation:
- full gate: security, performance, reliability, maintainability
- fast-track: security mandatory, others may downgrade to concerns-only scope
- 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