ln-500-story-quality-gate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Story Quality Gate

Story质量门控

Two-pass Story review with 4-level Gate verdict, Quality Score calculation, and NFR validation (security, performance, reliability, maintainability).

包含4级门控 verdict、质量分数计算和NFR验证（安全性、性能、可靠性、可维护性）的两轮Story评审流程。

Purpose & Scope

目的与范围

Pass 1 (after impl tasks Done): run code-quality, lint, regression, and manual testing; if all pass, create/confirm test task; otherwise create targeted fix/refactor tasks and stop.
Pass 2 (after test task Done): verify tests/coverage/priority limits, calculate Quality Score and NFR validation, close Story to Done or create fix tasks.
Delegates work to ln-501/ln-502 workers and ln-510-test-planner.

第一轮（实现任务完成后）：执行代码质量检查、代码规范检查（lint）、回归测试和手动测试；若全部通过，则创建/确认测试任务；否则创建针对性修复/重构任务并终止流程。
第二轮（测试任务完成后）：验证测试/覆盖率/优先级限制，计算质量分数并完成NFR验证，将Story标记为完成或创建修复任务。
将工作委托给ln-501/ln-502工作单元以及ln-510-test-planner。

4-Level Gate Model

4级门控模型

Level	Meaning	Action
PASS	All checks pass, no issues	Story → Done
CONCERNS	Minor issues, acceptable risk	Story → Done with comment noting concerns
FAIL	Blocking issues found	Create fix tasks, return to ln-400
WAIVED	Issues acknowledged by user	Story → Done with waiver reason documented

Verdict calculation:

FAIL

if any check fails.

CONCERNS

if minor issues exist.

PASS

if all clean.

级别	含义	操作
PASS	所有检查通过，无问题	Story → 完成
CONCERNS	存在次要问题，风险可接受	Story → 完成并在备注中说明问题
FAIL	发现阻塞性问题	创建修复任务，返回至ln-400
WAIVED	用户已确认问题	Story → 完成并记录豁免原因

Verdict计算规则： 若任意检查失败则标记为

FAIL

。若存在次要问题则标记为

CONCERNS

。所有检查无问题则标记为

PASS

。

Quality Score

质量分数

Formula:

Quality Score = 100 - (20 × FAIL_count) - (10 × CONCERN_count)

Score Range	Status	Action
90-100	✅ Excellent	PASS
70-89	⚠️ Acceptable	CONCERNS (proceed with notes)
50-69	❌ Below threshold	FAIL (create fix tasks)
<50	🚨 Critical	FAIL (urgent priority)

计算公式：

Quality Score = 100 - (20 × FAIL_count) - (10 × CONCERN_count)

分数范围	状态	操作
90-100	✅ 优秀	PASS
70-89	⚠️ 可接受	CONCERNS（记录后继续）
50-69	❌ 低于阈值	FAIL（创建修复任务）
<50	🚨 严重	FAIL（高优先级）

NFR Validation

NFR验证

Evaluate 4 non-functional requirement dimensions:

NFR	Checks	Issue Prefix
Security	Auth, input validation, secrets exposure	SEC-
Performance	N+1 queries, caching, response times	PERF-
Reliability	Error handling, retries, timeouts	REL-
Maintainability	DRY, SOLID, cyclomatic complexity	MNT-

Additional prefixes:

TEST-

(coverage gaps),

ARCH-

(architecture issues),

DOC-

(documentation gaps),

DEP-

(Story/Task dependencies),

COV-

(AC coverage quality),

DB-

(database schema),

AC-

(AC validation)

NFR verdict per dimension: PASS / CONCERNS / FAIL

从4个非功能需求维度进行评估：

NFR	检查内容	问题前缀
Security	认证、输入验证、敏感信息泄露	SEC-
Performance	N+1查询、缓存、响应时间	PERF-
Reliability	错误处理、重试机制、超时设置	REL-
Maintainability	DRY原则、SOLID原则、圈复杂度	MNT-

额外问题前缀：

TEST-

（覆盖率缺口）、

ARCH-

（架构问题）、

DOC-

（文档缺口）、

DEP-

（Story/任务依赖）、

COV-

（验收标准覆盖质量）、

DB-

（数据库 schema）、

AC-

（验收标准验证）

各维度NFR verdict： PASS / CONCERNS / FAIL

When to Use

使用时机

Pass 1: all implementation tasks Done; test task missing or not Done.
Pass 2: test task exists and is Done.
Explicit
```
pass
```
parameter can force 1 or 2; otherwise auto-detect by test task status.

第一轮：所有实现任务完成；测试任务缺失或未完成。
第二轮：测试任务已存在且已完成。
可通过显式
```
pass
```
参数指定执行第一轮或第二轮；否则根据测试任务状态自动检测。

Workflow (concise)

工作流（精简版）

Phase 1 Discovery: Auto-discover team/config; select Story; load Story + task metadata (no descriptions), detect test task status.
Pass 1 flow (fail fast):
1. Invoke ln-501-code-quality-checker. If issues -> create refactor task (Backlog), stop. 1.5) Criteria Validation (Story-level checks) - see
```
references/criteria_validation.md
```
  :
  - Check #1: Story Dependencies (no forward deps within Epic) - if FAIL → create [DEP-] task, stop.
  - Check #2: AC-Task Coverage Quality (STRONG/WEAK/MISSING scoring) - if FAIL/CONCERNS → create [BUG-]/[COV-] tasks, stop.
  - Check #3: Database Creation Principle (schema scope matches Story) - if FAIL → create [DB-] task, stop.
2. Run all linters from tech_stack.md. If fail -> create lint-fix task, stop.
3. Invoke ln-502-regression-checker. If fail -> create regression-fix task, stop.
4. Invoke ln-510-test-planner (orchestrates: ln-511-test-researcher → ln-512-manual-tester → ln-513-auto-test-planner). If manual testing fails -> create bug-fix task, stop. If all passed -> test task created/updated.
5. If test task exists and Done, jump to Pass 2; if exists but not Done, report status and stop.
Pass 2 flow (after test task Done):
1. Load Story/test task; read test plan/results and manual testing comment from Pass 1.
2. Verify limits and priority: Priority ≤15; E2E 2-5, Integration 0-8, Unit 0-15, total 10-28; tests focus on business logic (no framework/DB/library tests).
3. Ensure Priority ≤15 scenarios and Story AC are covered by tests; infra/docs updates present.
4. Calculate Quality Score and NFR validation (see formulas above):
  - Run NFR checks per dimensions table
  - Assign issue prefixes: SEC-, PERF-, REL-, MNT-, TEST-, ARCH-, DOC-
  - Calculate Quality Score
5. Determine Gate verdict per 4-Level Gate Model above

TodoWrite format (mandatory): Add pass steps to todos before starting:

Pass 1:
- Invoke ln-501-code-quality-checker (in_progress)
- Pass 1.5: Criteria Validation (Story deps, AC coverage, DB schema) (pending)
- Run linters from tech_stack.md (pending)
- Invoke ln-502-regression-checker (pending)
- Invoke ln-510-test-planner (research + manual + auto tests) (pending)

Pass 2:
- Verify test task coverage (in_progress)
- Mark Story Done (pending)

Mark each as in_progress when starting, completed when done. On failure, mark remaining as skipped.

阶段1 发现： 自动识别团队/配置；选择Story；加载Story + 任务元数据（不含描述），检测测试任务状态。
第一轮流程（快速失败）：
1. 调用ln-501-code-quality-checker。若存在问题→创建重构任务（Backlog），终止流程。 1.5) 标准验证（Story级检查） - 详见
```
references/criteria_validation.md
```
  :
  - 检查1：Story依赖（Epic内无前置依赖）- 若失败→创建[DEP-]任务，终止流程。
  - 检查2：验收标准-任务覆盖质量（STRONG/WEAK/MISSING评分）- 若失败/存在问题→创建[BUG-]/[COV-]任务，终止流程。
  - 检查3：数据库创建原则（schema范围与Story匹配）- 若失败→创建[DB-]任务，终止流程。
2. 执行tech_stack.md中所有代码规范检查工具。若失败→创建代码规范修复任务，终止流程。
3. 调用ln-502-regression-checker。若失败→创建回归修复任务，终止流程。
4. 调用ln-510-test-planner（编排流程：ln-511-test-researcher → ln-512-manual-tester → ln-513-auto-test-planner）。若手动测试失败→创建bug修复任务，终止流程。若全部通过→创建/更新测试任务。
5. 若测试任务已存在且已完成，跳转至第二轮；若已存在但未完成，报告状态并终止流程。
第二轮流程（测试任务完成后）：
1. 加载Story/测试任务；读取第一轮的测试计划/结果和手动测试备注。
2. 验证限制条件和优先级：优先级≤15；端到端（E2E）测试2-5个，集成测试0-8个，单元测试0-15个，总数10-28个；测试需聚焦业务逻辑（不含框架/数据库/库测试）。
3. 确保优先级≤15的场景和Story验收标准均被测试覆盖；基础设施/文档已更新。
4. 计算质量分数并完成NFR验证（见上述公式）：
  - 按维度表执行NFR检查
  - 分配问题前缀：SEC-、PERF-、REL-、MNT-、TEST-、ARCH-、DOC-
  - 计算质量分数
5. 根据4级门控模型确定最终verdict

TodoWrite格式（强制要求）： 开始前需在待办事项中添加流程步骤：

Pass 1:
- Invoke ln-501-code-quality-checker (in_progress)
- Pass 1.5: Criteria Validation (Story deps, AC coverage, DB schema) (pending)
- Run linters from tech_stack.md (pending)
- Invoke ln-502-regression-checker (pending)
- Invoke ln-510-test-planner (research + manual + auto tests) (pending)

Pass 2:
- Verify test task coverage (in_progress)
- Mark Story Done (pending)

开始执行时标记为in_progress，完成后标记为completed。若失败，标记剩余步骤为skipped。

Worker Invocation (MANDATORY)

工作单元调用（强制要求）

Step	Worker	Context	Rationale
Code Quality	ln-501-code-quality-checker	Separate (Task tool)	Independent analysis, focused on DRY/KISS/YAGNI
Regression	ln-502-regression-checker	Shared (direct Skill tool)	Needs Story context and previous check results
Test Planning	ln-510-test-planner	Shared (direct Skill tool)	Needs full Gate context for test planning

ln-501 invocation (Separate Context):

Task(description: "Code quality check via ln-501",
     prompt: "Execute ln-501-code-quality-checker. Read skill from ln-501-code-quality-checker/SKILL.md. Story: {storyId}",
     subagent_type: "general-purpose")

ln-501 result contract (Task tool return): Task tool returns worker's final message. Parse for YAML block:

```
verdict: PASS | CONCERNS | ISSUES_FOUND
```
```
quality_score: 0-100
```

issues: [{id, severity, finding, action}]

If verdict = ISSUES_FOUND → create refactor task (Backlog), stop Pass 1.

ln-502 and ln-510: Invoke via direct Skill tool — workers see Gate context.

Note: ln-510 orchestrates the full test pipeline (ln-511 research → ln-512 manual → ln-513 auto tests).

❌ FORBIDDEN SHORTCUTS (Anti-Patterns):

Running
```
mypy
```
,
```
ruff
```
,
```
pytest
```
directly instead of invoking ln-501/ln-502
Doing "minimal quality check" (just linters) and skipping ln-510 test planning
Asking user "Want me to run the full skill?" after doing partial checks
Marking steps as "completed" in todo without invoking the actual skill
Any command execution that should be delegated to a worker skill

✅ CORRECT BEHAVIOR:

Use
```
Skill(skill: "ln-50X-...")
```
for EVERY step — NO EXCEPTIONS
Wait for each skill to complete before proceeding
If skill fails → create fix task → STOP (fail fast)
Never bypass skills with "I'll just run the command myself"

ZERO TOLERANCE: If you find yourself running quality commands directly (mypy, ruff, pytest, curl) instead of invoking the appropriate skill, STOP and use Skill tool instead.

步骤	工作单元	上下文	理由
代码质量检查	ln-501-code-quality-checker	独立（任务工具）	独立分析，聚焦DRY/KISS/YAGNI原则
回归测试	ln-502-regression-checker	共享（直接Skill工具）	需要Story上下文和之前的检查结果
测试规划	ln-510-test-planner	共享（直接Skill工具）	需要完整的门控上下文进行测试规划

ln-501调用（独立上下文）：

Task(description: "Code quality check via ln-501",
     prompt: "Execute ln-501-code-quality-checker. Read skill from ln-501-code-quality-checker/SKILL.md. Story: {storyId}",
     subagent_type: "general-purpose")

ln-501结果约定（任务工具返回）： 任务工具返回工作单元的最终消息。解析YAML块：

```
verdict: PASS | CONCERNS | ISSUES_FOUND
```
```
quality_score: 0-100
```

issues: [{id, severity, finding, action}]

若verdict = ISSUES_FOUND → 创建重构任务（Backlog），终止第一轮流程。

ln-502和ln-510： 通过直接Skill工具调用 — 工作单元可查看门控上下文。

注意： ln-510编排完整的测试流水线（ln-511调研 → ln-512手动测试 → ln-513自动化测试规划）。

❌ 禁止的捷径（反模式）：

直接运行
```
mypy
```
、
```
ruff
```
、
```
pytest
```
而非调用ln-501/ln-502
仅执行“最低限度质量检查”（仅代码规范检查）并跳过ln-510测试规划
执行部分检查后询问用户“是否需要我运行完整的skill？”
未实际调用skill就将步骤标记为“completed”
任何应委托给工作单元skill的命令执行操作

✅ 正确行为：

每一步都使用
```
Skill(skill: "ln-50X-...")
```
— 无例外
等待每个skill完成后再继续
若skill失败→创建修复任务→终止（快速失败）
绝不以“我自己来运行命令”为由绕过skill

零容忍： 若发现你直接运行质量检查命令（mypy、ruff、pytest、curl）而非调用对应的skill，请立即停止并改用Skill工具。

Critical Rules

关键规则

Early-exit: any failure creates a specific task and stops Pass 1/2.
Single source of truth: rely on Linear metadata for tasks; kanban is updated by workers/ln-400.
Task creation via skills only (ln-510/ln-301); this skill never edits tasks directly.
Pass 2 only runs when test task is Done; otherwise return error/status.
Language preservation in comments (EN/RU).

提前终止：任何失败都会创建特定任务并终止第一轮/第二轮流程。
单一事实来源：依赖Linear元数据获取任务信息；看板由工作单元/ln-400更新。
仅通过skill创建任务（ln-510/ln-301）；本skill从不直接编辑任务。
仅当测试任务完成时才执行第二轮流程；否则返回错误/状态。
备注保留原语言（英文/俄文）。

Definition of Done

完成定义

Pass 1: ln-501 pass OR refactor task created; linters pass OR lint-fix task created; ln-502 pass OR regression-fix task created; ln-510 pipeline pass (research + manual + auto tests) OR bug-fix task created; test task created/updated; exits.
Pass 2: test task verified (priority/limits/coverage/infra/docs); Quality Score calculated; NFR validation completed; Gate verdict determined (PASS/CONCERNS/FAIL/WAIVED).

Gate output format:

yaml

gate: PASS | CONCERNS | FAIL | WAIVED
quality_score: {0-100}
nfr_validation:
  security: PASS | CONCERNS | FAIL
  performance: PASS | CONCERNS | FAIL
  reliability: PASS | CONCERNS | FAIL
  maintainability: PASS | CONCERNS | FAIL
issues: [{id: "SEC-001", severity: high|medium|low, finding: "...", action: "..."}]

Story set to Done (PASS/CONCERNS/WAIVED) or fix tasks created (FAIL); comment with gate verdict posted.

第一轮：ln-501通过或已创建重构任务；代码规范检查通过或已创建代码规范修复任务；ln-502通过或已创建回归修复任务；ln-510流水线通过（调研+手动+自动化测试）或已创建bug修复任务；测试任务已创建/更新；流程退出。
第二轮：已验证测试任务（优先级/限制/覆盖率/基础设施/文档）；已计算质量分数；已完成NFR验证；已确定门控verdict（PASS/CONCERNS/FAIL/WAIVED）。

门控输出格式：

yaml

gate: PASS | CONCERNS | FAIL | WAIVED
quality_score: {0-100}
nfr_validation:
  security: PASS | CONCERNS | FAIL
  performance: PASS | CONCERNS | FAIL
  reliability: PASS | CONCERNS | FAIL
  maintainability: PASS | CONCERNS | FAIL
issues: [{id: "SEC-001", severity: high|medium|low, finding: "...", action: "..."}]

Story被标记为完成（PASS/CONCERNS/WAIVED）或已创建修复任务（FAIL）；已发布包含门控verdict的备注。

Reference Files

参考文件

Orchestrator lifecycle:

shared/references/orchestrator_pattern.md

Task delegation pattern:

shared/references/task_delegation_pattern.md

AC validation rules:

shared/references/ac_validation_rules.md

Criteria Validation:
```
references/criteria_validation.md
```
(Story deps, AC coverage quality, DB schema checks from ln-310)
Gate levels:
```
references/gate_levels.md
```
(detailed scoring rules and thresholds)

Workers:

../ln-501-code-quality-checker/SKILL.md

../ln-502-regression-checker/SKILL.md

Test planning orchestrator:
```
../ln-510-test-planner/SKILL.md
```
(coordinates ln-511/512/513)
Tech stack/linters:
```
docs/project/tech_stack.md
```

Version: 6.0.0 (BREAKING: Added Pass 1.5 Criteria Validation with 3 checks from ln-310 - Story dependencies, AC-Task Coverage Quality (STRONG/WEAK/MISSING), Database Creation Principle. New issue prefixes: DEP-, COV-, DB-, AC-. Closes validation-execution gap at Story level per BMAD Method best practices.) Last Updated: 2026-02-03

编排器生命周期：

shared/references/orchestrator_pattern.md

任务委托模式：

shared/references/task_delegation_pattern.md

验收标准验证规则：

shared/references/ac_validation_rules.md

标准验证：
```
references/criteria_validation.md
```
（来自ln-310的Story依赖、验收标准覆盖质量、数据库schema检查）
门控级别：
```
references/gate_levels.md
```
（详细评分规则和阈值）

工作单元：

../ln-501-code-quality-checker/SKILL.md

../ln-502-regression-checker/SKILL.md

测试编排器：
```
../ln-510-test-planner/SKILL.md
```
（协调ln-511/512/513）
技术栈/代码规范工具：
```
docs/project/tech_stack.md
```

版本： 6.0.0（重大变更：新增第一轮1.5阶段标准验证，包含来自ln-310的3项检查 - Story依赖、验收标准-任务覆盖质量（STRONG/WEAK/MISSING）、数据库创建原则。新增问题前缀：DEP-、COV-、DB-、AC-。根据BMAD方法最佳实践填补了Story级别的验证-执行缺口。） 最后更新日期： 2026-02-03