ln-500-story-quality-gate

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:

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:
3. If found with verdict=FAIL, load payload.metadata.rework_hint as previous_cycle context.
4. Record cycle_number (1-based, incremented from prior artifact count).
5. Build gate manifest:
6. story_id
7. task_provider
8. project_root
9. worktree_dir
10. branch
11. fast_track_policy
12. nfr_policy
13. test_task_policy
14. previous_cycle (null or loaded rework_hint)
15. cycle_number
16. 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:
3. fast_track
4. gate scope summary

Phase 3: Quality Checks

1. Compute:
2. childRunId = {parent_run_id}--ln-510--{storyId}
3. childSummaryArtifactPath = .hex-skills/runtime-artifacts/runs/{parent_run_id}/story-quality/{storyId}.json
4. Materialize child manifest and start child coordinator runtime:
5. node references/scripts/quality-runtime/cli.mjs start --story {storyId} --manifest-file .hex-skills/story-gate/ln-510--{storyId}_manifest.json --run-id {childRunId}
6. Checkpoint PHASE_3_QUALITY_CHECKS with:
7. child_run.worker=ln-510
8. child_run.run_id={childRunId}
9. child_run.summary_artifact_path={childSummaryArtifactPath}
10. child_run.phase_context=quality_checks
11. Invoke ln-510-quality-coordinator with managed transport inputs:
12. full mode: Skill(skill: "ln-510-quality-coordinator", args: "{storyId} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
13. fast-track: Skill(skill: "ln-510-quality-coordinator", args: "{storyId} --fast-track --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
14. full mode with prior cycle: append --previous-cycle-focus "{blocking_categories}" when previous_cycle is not null
15. Read child story-quality artifact only, then record-quality.
16. Before another quality/rework cycle, compare FAIL evidence against prior cycle:
17. progress = new quality artifact, new fix tasks, code delta, status delta, or changed blocking category
18. same FAIL with no new evidence = record loop health and pause before another rework cycle
19. Checkpoint PHASE_3_QUALITY_CHECKS with the recorded quality summary.
20. 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:
2. no test task -> invoke ln-520
3. fast-track -> invoke simplified ln-520
4. test task already exists and is terminal (Done | SKIPPED | VERIFIED) -> checkpoint as reused
5. When invoking ln-520, compute:
6. childRunId = {parent_run_id}--ln-520--{storyId}
7. childSummaryArtifactPath = .hex-skills/runtime-artifacts/runs/{parent_run_id}/story-tests/{storyId}.json
8. Materialize child manifest and start child coordinator runtime:
9. 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}
10. Checkpoint PHASE_4_TEST_PLANNING with:
11. child_run.worker=ln-520
12. child_run.run_id={childRunId}
13. child_run.summary_artifact_path={childSummaryArtifactPath}
14. child_run.phase_context=test_planning
15. Invoke ln-520-test-planner with managed transport inputs:
16. normal mode: Skill(skill: "ln-520-test-planner", args: "{storyId} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
17. simplified mode: Skill(skill: "ln-520-test-planner", args: "{storyId} --simplified --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
18. Read child story-tests artifact only, then record-test-status.
19. Checkpoint PHASE_4_TEST_PLANNING.

Phase 5: Test Verification

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

Phase 6: Verdict

1. Calculate quality_score.
2. Evaluate NFR validation:
3. full gate: security, performance, reliability, maintainability
4. fast-track: security mandatory, others may downgrade to concerns-only scope
5. 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:
6. (1) Actor trigger — what initiates the scenario (user sends message, timer fires, webhook arrives, event is enqueued)
7. (2) Entry point — the named mechanism (MCP tool, API endpoint, CLI command, UI component, chat handler, config file, cron handler)
8. (3) Discovery — how the actor's system finds/loads the mechanism at runtime (config registration, route mounting, plugin loading, system prompt, environment variable)
9. (4) Usage context — what the actor's system needs