Back to Details

doc-tspec-validator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-tspec-validator

doc-tspec-validator

Validate Test Specification (TSPEC) documents against Layer 10 schema standards.
依据Layer 10 schema标准验证测试规范（TSPEC）文档。

Purpose

用途

Validates TSPEC documents for:
  • YAML frontmatter metadata compliance
  • Section structure (test specification sections)
  • Document Control completeness
  • Cumulative tagging (8 required: @brd, @prd, @ears, @bdd, @adr, @sys, @req, @spec)
  • TASKS-Ready scoring
  • File naming convention (TSPEC-NN_{slug}.md or {TYPE}-NN_{slug}.md)
  • Element ID format (TSPEC.NN.TT.SS where TT is 40-43)
  • Test type validation (UTEST/ITEST/STEST/FTEST)
验证TSPEC文档是否符合以下要求：
  • YAML前置元数据合规性
  • 章节结构（测试规范章节）
  • 文档控制完整性
  • 累积标签（需8个必填标签：@brd、@prd、@ears、@bdd、@adr、@sys、@req、@spec）
  • TASKS就绪评分
  • 文件命名规范（TSPEC-NN_{slug}.md 或 {TYPE}-NN_{slug}.md）
  • 元素ID格式（TSPEC.NN.TT.SS，其中TT为40-43）
  • 测试类型验证（UTEST/ITEST/STEST/FTEST）

Activation

触发时机

Invoke when:
  • User requests validation of TSPEC documents
  • After creating/modifying TSPEC artifacts
  • Before generating downstream artifacts (TASKS)
  • As part of quality gate checks
  • Validating test coverage matrices
在以下场景中调用：
  • 用户请求验证TSPEC文档时
  • 创建/修改TSPEC工件后
  • 生成下游工件（TASKS）前
  • 作为质量门检查的一部分
  • 验证测试覆盖矩阵时

Schema Reference

Schema参考

ItemValue
TSPEC Index
ai_dev_flow/10_TSPEC/TSPEC-00_index.md
UTEST Template
ai_dev_flow/10_TSPEC/UTEST/UTEST-MVP-TEMPLATE.md
ITEST Template
ai_dev_flow/10_TSPEC/ITEST/ITEST-MVP-TEMPLATE.md
STEST Template
ai_dev_flow/10_TSPEC/STEST/STEST-MVP-TEMPLATE.md
FTEST Template
ai_dev_flow/10_TSPEC/FTEST/FTEST-MVP-TEMPLATE.md
Layer10
Artifact TypeTSPEC
项值
TSPEC索引
ai_dev_flow/10_TSPEC/TSPEC-00_index.md
UTEST模板
ai_dev_flow/10_TSPEC/UTEST/UTEST-MVP-TEMPLATE.md
ITEST模板
ai_dev_flow/10_TSPEC/ITEST/ITEST-MVP-TEMPLATE.md
STEST模板
ai_dev_flow/10_TSPEC/STEST/STEST-MVP-TEMPLATE.md
FTEST模板
ai_dev_flow/10_TSPEC/FTEST/FTEST-MVP-TEMPLATE.md
层级10
工件类型TSPEC

Validation Checklist

验证检查清单

0. Folder Structure Validation (BLOCKING)

0. 文件夹结构验证（阻塞性检查）

Nested Folder Rule: ALL TSPEC documents MUST be in nested folders regardless of size.
Required Structure:
TSPEC TypeRequired Location
UTEST
docs/10_TSPEC/UTEST/UTEST-NN_{slug}/UTEST-NN_{slug}.md
ITEST
docs/10_TSPEC/ITEST/ITEST-NN_{slug}/ITEST-NN_{slug}.md
STEST
docs/10_TSPEC/STEST/STEST-NN_{slug}/STEST-NN_{slug}.md
FTEST
docs/10_TSPEC/FTEST/FTEST-NN_{slug}/FTEST-NN_{slug}.md
Validation:
1. Check document is inside a nested folder: docs/10_TSPEC/{TYPE}/{TYPE}-NN_{slug}/
2. Verify folder name matches TSPEC ID pattern: {TYPE}-NN_{slug}
3. Verify file name matches folder: {TYPE}-NN_{slug}.md
4. Parent path must be: docs/10_TSPEC/{TYPE}/
Example Valid Structure:
docs/10_TSPEC/
├── UTEST/
│   ├── UTEST-01_auth_service/
│   │   ├── UTEST-01_auth_service.md   ✓ Valid
│   │   ├── UTEST-01.R_review_report_v001.md
│   │   └── .drift_cache.json
│   └── UTEST-02_session_service/
│       └── UTEST-02_session_service.md ✓ Valid
├── ITEST/
│   └── ITEST-01_api_integration/
│       └── ITEST-01_api_integration.md ✓ Valid
├── STEST/
│   └── STEST-01_deployment_smoke/
│       └── STEST-01_deployment_smoke.md ✓ Valid
└── FTEST/
    └── FTEST-01_user_workflow/
        └── FTEST-01_user_workflow.md   ✓ Valid
Invalid Structure:
docs/10_TSPEC/
├── UTEST/
│   ├── UTEST-01_auth_service.md       ✗ NOT in nested folder
Error Codes:
CodeSeverityDescription
TSPEC-E030ERRORTSPEC not in nested folder (BLOCKING)
TSPEC-E031ERRORFolder name doesn't match TSPEC ID
TSPEC-E032ERRORFile name doesn't match folder name
TSPEC-E033ERRORTSPEC not in correct type subdirectory
This check is BLOCKING - TSPEC must pass folder structure validation before other checks proceed.
嵌套文件夹规则：所有TSPEC文档无论大小，必须存放在嵌套文件夹中。
必填结构：
TSPEC类型必填存放路径
UTEST
docs/10_TSPEC/UTEST/UTEST-NN_{slug}/UTEST-NN_{slug}.md
ITEST
docs/10_TSPEC/ITEST/ITEST-NN_{slug}/ITEST-NN_{slug}.md
STEST
docs/10_TSPEC/STEST/STEST-NN_{slug}/STEST-NN_{slug}.md
FTEST
docs/10_TSPEC/FTEST/FTEST-NN_{slug}/FTEST-NN_{slug}.md
验证步骤：
1. 检查文档是否位于嵌套文件夹内：docs/10_TSPEC/{TYPE}/{TYPE}-NN_{slug}/
2. 验证文件夹名称是否匹配TSPEC ID格式：{TYPE}-NN_{slug}
3. 验证文件名是否与文件夹名称一致：{TYPE}-NN_{slug}.md
4. 父路径必须为：docs/10_TSPEC/{TYPE}/
有效结构示例：
docs/10_TSPEC/
├── UTEST/
│   ├── UTEST-01_auth_service/
│   │   ├── UTEST-01_auth_service.md   ✓ 有效
│   │   ├── UTEST-01.R_review_report_v001.md
│   │   └── .drift_cache.json
│   └── UTEST-02_session_service/
│       └── UTEST-02_session_service.md ✓ 有效
├── ITEST/
│   └── ITEST-01_api_integration/
│       └── ITEST-01_api_integration.md ✓ 有效
├── STEST/
│   └── STEST-01_deployment_smoke/
│       └── STEST-01_deployment_smoke.md ✓ 有效
└── FTEST/
    └── FTEST-01_user_workflow/
        └── FTEST-01_user_workflow.md   ✓ 有效
无效结构示例：
docs/10_TSPEC/
├── UTEST/
│   ├── UTEST-01_auth_service.md       ✗ 未存放在嵌套文件夹中
错误代码：
代码严重程度描述
TSPEC-E030错误TSPEC未存放在嵌套文件夹中（阻塞性检查）
TSPEC-E031错误文件夹名称与TSPEC ID不匹配
TSPEC-E032错误文件名与文件夹名称不匹配
TSPEC-E033错误TSPEC未存放在正确的类型子目录中
此检查为阻塞性检查 - TSPEC必须通过文件夹结构验证后，才能进行其他检查。

1. Metadata Validation

1. 元数据验证

yaml
Required custom_fields:
  document_type: ["tspec", "utest", "itest", "stest", "ftest", "template"]
  artifact_type: "TSPEC"
  layer: 10
  architecture_approaches: [array format]
  priority: ["primary", "shared", "fallback"]
  development_status: ["active", "draft", "deprecated", "reference"]

Required tags:
  - tspec (or utest, itest, stest, ftest)
  - layer-10-artifact

Forbidden tag patterns:
  - "^test-specification$"
  - "^tspec-\\d{3}$"
  - "^unit-test$"
  - "^integration-test$"
yaml
必填custom_fields:
  document_type: ["tspec", "utest", "itest", "stest", "ftest", "template"]
  artifact_type: "TSPEC"
  layer: 10
  architecture_approaches: [数组格式]
  priority: ["primary", "shared", "fallback"]
  development_status: ["active", "draft", "deprecated", "reference"]

必填tags:
  - tspec（或utest、itest、stest、ftest）
  - layer-10-artifact

禁用标签模式:
  - "^test-specification$"
  - "^tspec-\\d{3}$"
  - "^unit-test$"
  - "^integration-test$"

2. Structure Validation

2. 结构验证

Required Sections (All TSPEC Types):
SectionTitleRequired
1Document ControlMANDATORY
2Test ScopeMANDATORY
3Test Case IndexMANDATORY
4Test Case DetailsMANDATORY
5Coverage MatrixMANDATORY
6TraceabilityMANDATORY
7Error CasesMANDATORY
Section Format: 
## N. Title
(numbered H2 headings)
所有TSPEC类型必填章节：
章节标题必填性
1文档控制强制
2测试范围强制
3测试用例索引强制
4测试用例详情强制
5覆盖矩阵强制
6追溯性强制
7错误场景强制
章节格式：
## N. 标题
（带编号的H2标题）

3. Document Control Required Fields

3. 文档控制必填字段

FieldDescriptionRequired
StatusDraft/Review/Approved/ImplementedMANDATORY
VersionSemantic versioning (X.Y.Z)MANDATORY
Date CreatedYYYY-MM-DD formatMANDATORY
Last UpdatedYYYY-MM-DD formatMANDATORY
AuthorTest author nameMANDATORY
ComponentComponent/module under testMANDATORY
SPEC ReferenceSPEC-NNMANDATORY
Coverage TargetXX%MANDATORY
TASKS-Ready Score
XX/100 (Target: see type-specific)
MANDATORY
字段描述必填性
状态草稿/评审/已批准/已实现强制
版本语义化版本（X.Y.Z）强制
创建日期YYYY-MM-DD格式强制
最后更新日期YYYY-MM-DD格式强制
作者测试文档作者姓名强制
组件被测组件/模块强制
SPEC参考SPEC-NN强制
覆盖目标XX%强制
TASKS就绪评分
XX/100（目标：见类型特定要求）
强制

4. Test Type Element Codes

4. 测试类型元素代码

Test TypeCodeAbbreviationTASKS-Ready Target
Unit Test40UTEST>=90%
Integration Test41ITEST>=85%
Smoke Test42STEST100%
Functional Test43FTEST>=85%
测试类型代码缩写TASKS就绪目标
单元测试40UTEST>=90%
集成测试41ITEST>=85%
冒烟测试42STEST100%
功能测试43FTEST>=85%

5. Element ID Format

5. 元素ID格式

Pattern: 
TSPEC.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
(4 segments, dot-separated)
Valid Element Type Codes: 40, 41, 42, 43 only
Examples:
Element IDValidTest Type
TSPEC.01.40.01
YesUnit Test
TSPEC.01.41.01
YesIntegration Test
TSPEC.01.42.01
YesSmoke Test
TSPEC.01.43.01
YesFunctional Test
TSPEC.01.44.01
NoInvalid code (44 not in 40-43)
TC-001
NoLegacy pattern
UT-001
NoLegacy pattern
Deprecated Patterns (Do NOT use):
  • TC-XXX
    - Use 
    TSPEC.NN.TT.SS
    instead
  • UT-XXX
    - Use 
    TSPEC.NN.40.SS
    instead
  • IT-XXX
    - Use 
    TSPEC.NN.41.SS
    instead
  • ST-XXX
    - Use 
    TSPEC.NN.42.SS
    instead
  • FT-XXX
    - Use 
    TSPEC.NN.43.SS
    instead
格式：
TSPEC.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
（4个段，点分隔）
有效元素类型代码：仅40、41、42、43
示例：
元素ID是否有效测试类型
TSPEC.01.40.01
是单元测试
TSPEC.01.41.01
是集成测试
TSPEC.01.42.01
是冒烟测试
TSPEC.01.43.01
是功能测试
TSPEC.01.44.01
否无效代码（44不在40-43范围内）
TC-001
否旧格式
UT-001
否旧格式
已弃用格式（禁止使用）：
  • TC-XXX
    - 请改用 
    TSPEC.NN.TT.SS
  • UT-XXX
    - 请改用 
    TSPEC.NN.40.SS
  • IT-XXX
    - 请改用 
    TSPEC.NN.41.SS
  • ST-XXX
    - 请改用 
    TSPEC.NN.42.SS
  • FT-XXX
    - 请改用 
    TSPEC.NN.43.SS

6. Naming Compliance (doc-naming integration)

6. 命名合规性（集成doc-naming）

File Naming Patterns:
PatternExampleDocument Type
UTEST-NN_{slug}.md
UTEST-01_auth_service_unit.md
Unit Test
ITEST-NN_{slug}.md
ITEST-01_api_integration.md
Integration Test
STEST-NN_{slug}.md
STEST-01_deployment_smoke.md
Smoke Test
FTEST-NN_{slug}.md
FTEST-01_order_processing.md
Functional Test
Directory Structure:
docs/10_TSPEC/
  UTEST/
    UTEST-01_{slug}.md
  ITEST/
    ITEST-01_{slug}.md
  STEST/
    STEST-01_{slug}.md
  FTEST/
    FTEST-01_{slug}.md
  TSPEC-00_TRACEABILITY_MATRIX.md
文件命名格式：
格式示例文档类型
UTEST-NN_{slug}.md
UTEST-01_auth_service_unit.md
单元测试
ITEST-NN_{slug}.md
ITEST-01_api_integration.md
集成测试
STEST-NN_{slug}.md
STEST-01_deployment_smoke.md
冒烟测试
FTEST-NN_{slug}.md
FTEST-01_order_processing.md
功能测试
目录结构：
docs/10_TSPEC/
  UTEST/
    UTEST-01_{slug}.md
  ITEST/
    ITEST-01_{slug}.md
  STEST/
    STEST-01_{slug}.md
  FTEST/
    FTEST-01_{slug}.md
  TSPEC-00_TRACEABILITY_MATRIX.md

7. Cumulative Tagging Requirements

7. 累积标签要求

Layer 10 Cumulative Tags (8 Required):
markdown
@brd: BRD.NN.TT.SS
@prd: PRD.NN.TT.SS
@ears: EARS.NN.25.SS
@bdd: BDD.NN.14.SS
@adr: ADR-NN
@sys: SYS.NN.26.SS
@req: REQ.NN.27.SS
@spec: SPEC-NN
Optional (9th tag if CTR exists):
markdown
@ctr: CTR-NN
Tag Format Convention:
NotationFormatArtifacts
DashTYPE-NNADR, SPEC, CTR
DotTYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, TSPEC
Layer 10累积标签（8个必填）：
markdown
@brd: BRD.NN.TT.SS
@prd: PRD.NN.TT.SS
@ears: EARS.NN.25.SS
@bdd: BDD.NN.14.SS
@adr: ADR-NN
@sys: SYS.NN.26.SS
@req: REQ.NN.27.SS
@spec: SPEC-NN
可选标签（若存在CTR则需第9个）：
markdown
@ctr: CTR-NN
标签格式约定：
符号格式适用工件
短横线TYPE-NNADR、SPEC、CTR
点TYPE.NN.TT.SSBRD、PRD、EARS、BDD、SYS、REQ、TSPEC

8. Test Case Format Requirements

8. 测试用例格式要求

Each test case MUST include:
markdown
undefined
每个测试用例必须包含：
markdown
undefined

TSPEC.NN.TT.SS: [Test Name]

TSPEC.NN.TT.SS: [测试名称]

Category: [Logic] | [State] | [Validation] | [Edge] | [Integration] | [Critical Path]
Traceability:
  • @req: REQ.NN.27.XX
  • @spec: SPEC-NN (Section X.Y)
Input/Output Table:
InputExpected OutputNotes
param1="valid"
True
Happy path
param1=""
ValidationError
Empty input
Pseudocode: GIVEN valid input parameters WHEN function_under_test(param1) is called THEN result equals expected_output AND no side effects occur
Error Cases:
Error ConditionExpected Behavior
Invalid input typeRaise 
TypeError
undefined
分类：[逻辑] | [状态] | [验证] | [边界] | [集成] | [关键路径]
追溯性:
  • @req: REQ.NN.27.XX
  • @spec: SPEC-NN（章节X.Y）
输入/输出表:
输入预期输出备注
param1="valid"
True
正常路径
param1=""
ValidationError
空输入
伪代码: GIVEN 有效输入参数 WHEN 调用function_under_test(param1) THEN 结果等于预期输出 AND 无副作用产生
错误场景:
错误条件预期行为
无效输入类型抛出
TypeError
undefined

9. Coverage Matrix Validation

9. 覆盖矩阵验证

Required Format:
markdown
undefined
必填格式：
markdown
undefined

Coverage Matrix

覆盖矩阵

REQ IDREQ TitleTest IDsCoverage
REQ.NN.27.01[Title]TSPEC.NN.40.01, TSPEC.NN.40.03Covered
REQ.NN.27.02[Title]-NOT COVERED
Coverage Summary:
  • Total REQ elements: [N]
  • Covered: [N]
  • Coverage: [XX]%
undefined
REQ IDREQ标题测试ID覆盖状态
REQ.NN.27.01[标题]TSPEC.NN.40.01, TSPEC.NN.40.03已覆盖
REQ.NN.27.02[标题]-未覆盖
覆盖摘要:
  • 总REQ元素数：[N]
  • 已覆盖：[N]
  • 覆盖率：[XX]%
undefined

10. Type-Specific Requirements

10. 类型特定要求

UTEST (Unit Tests - Code 40)

UTEST（单元测试 - 代码40）

RequirementValue
TASKS-Ready Target>=90%
Required Tags@req, @spec
Test Categories[Logic], [State], [Validation], [Edge]
Function Coverage>=90%
Branch Coverage>=80%
要求值
TASKS就绪目标>=90%
必填标签@req、@spec
测试分类[逻辑]、[状态]、[验证]、[边界]
函数覆盖率>=90%
分支覆盖率>=80%

ITEST (Integration Tests - Code 41)

ITEST（集成测试 - 代码41）

RequirementValue
TASKS-Ready Target>=85%
Required Tags@ctr, @sys, @spec
Test Categories[Integration], [Contract], [Sequence]
Sequence DiagramsRequired for complex interactions
Mock StrategyMust be documented
要求值
TASKS就绪目标>=85%
必填标签@ctr、@sys、@spec
测试分类[集成]、[契约]、[序列]
序列图复杂交互场景必填
Mock策略必须文档化

STEST (Smoke Tests - Code 42)

STEST（冒烟测试 - 代码42）

RequirementValue
TASKS-Ready Target100%
Required Tags@ears, @bdd, @req
Test Categories[Critical Path], [Health Check], [Deployment]
Execution Time<5 minutes total
Critical Path Coverage100%
要求值
TASKS就绪目标100%
必填标签@ears、@bdd、@req
测试分类[关键路径]、[健康检查]、[部署]
执行时间总时长<5分钟
关键路径覆盖率100%

FTEST (Functional Tests - Code 43)

FTEST（功能测试 - 代码43）

RequirementValue
TASKS-Ready Target>=85%
Required Tags@sys, @threshold
Test Categories[Functional], [Scenario], [End-to-End]
SYS CoverageRequired
Threshold ReferencesMust include @threshold tags
要求值
TASKS就绪目标>=85%
必填标签@sys、@threshold
测试分类[功能]、[场景]、[端到端]
SYS覆盖率必填
阈值参考必须包含@threshold标签

Error Codes

错误代码

CodeSeverityDescription
TSPEC-E001ERRORMissing required tag 'tspec' (or type-specific: utest/itest/stest/ftest)
TSPEC-E002ERRORMissing required tag 'layer-10-artifact'
TSPEC-E003ERRORInvalid document_type value
TSPEC-E004ERRORInvalid architecture_approaches format (must be array)
TSPEC-E005ERRORForbidden tag pattern detected
TSPEC-E006ERRORMissing required section
TSPEC-E007ERRORMultiple H1 headings detected
TSPEC-E008ERRORSection numbering not sequential
TSPEC-E009ERRORDocument Control missing required fields
TSPEC-E010ERRORMissing Test Case Details (Section 4)
TSPEC-E011ERRORInvalid element type code (must be 40-43)
TSPEC-E012ERRORMissing cumulative tags (requires 8: @brd through @spec)
TSPEC-E013ERRORInvalid element ID format (not TSPEC.NN.TT.SS)
TSPEC-E014ERRORMissing upstream @spec tag
TSPEC-E015ERRORMissing Coverage Matrix (Section 5)
TSPEC-E016ERRORMissing SPEC Reference in Document Control
TSPEC-E017ERRORDeprecated ID pattern used (TC-XXX, UT-XXX, IT-XXX, ST-XXX, FT-XXX)
TSPEC-E018ERRORElement type code mismatch (e.g., using 40 in ITEST document)
TSPEC-E019ERRORMissing I/O table for test case
TSPEC-E020ERRORMissing traceability section
TSPEC-W001WARNINGFile name does not match format {TYPE}-NN_{slug}.md
TSPEC-W002WARNINGMissing pseudocode for complex test case
TSPEC-W003WARNINGTASKS-Ready Score below type-specific target
TSPEC-W004WARNINGCoverage percentage below target
TSPEC-W005WARNINGMissing error cases documentation
TSPEC-W006WARNINGMissing test fixtures documentation
TSPEC-W007WARNINGMissing mock strategy (ITEST only)
TSPEC-W008WARNINGExecution time exceeds 5 minutes (STEST only)
TSPEC-W009WARNINGMissing @threshold tags (FTEST only)
TSPEC-W010WARNINGMissing sequence diagrams for complex interactions (ITEST only)
TSPEC-I001INFOConsider adding performance targets for test execution
TSPEC-I002INFOConsider adding test data setup documentation
TSPEC-I003INFOConsider adding CI/CD integration notes
代码严重程度描述
TSPEC-E001错误缺失必填标签'tspec'（或类型特定标签：utest/itest/stest/ftest）
TSPEC-E002错误缺失必填标签'layer-10-artifact'
TSPEC-E003错误document_type值无效
TSPEC-E004错误architecture_approaches格式无效（必须为数组）
TSPEC-E005错误检测到禁用的标签模式
TSPEC-E006错误缺失必填章节
TSPEC-E007错误检测到多个H1标题
TSPEC-E008错误章节编号不连续
TSPEC-E009错误文档控制缺失必填字段
TSPEC-E010错误缺失测试用例详情（章节4）
TSPEC-E011错误元素类型代码无效（必须为40-43）
TSPEC-E012错误缺失累积标签（需8个：@brd至@spec）
TSPEC-E013错误元素ID格式无效（非TSPEC.NN.TT.SS）
TSPEC-E014错误缺失上游@spec标签
TSPEC-E015错误缺失覆盖矩阵（章节5）
TSPEC-E016错误文档控制中缺失SPEC参考
TSPEC-E017错误使用了已弃用的ID格式（TC-XXX、UT-XXX、IT-XXX、ST-XXX、FT-XXX）
TSPEC-E018错误元素类型代码不匹配（例如在ITEST文档中使用40）
TSPEC-E019错误测试用例缺失输入输出表
TSPEC-E020错误缺失追溯性章节
TSPEC-W001警告文件名不符合{TYPE}-NN_{slug}.md格式
TSPEC-W002警告复杂测试用例缺失伪代码
TSPEC-W003警告TASKS就绪评分未达类型特定目标
TSPEC-W004警告覆盖率未达目标
TSPEC-W005警告缺失错误场景文档
TSPEC-W006警告缺失测试夹具文档
TSPEC-W007警告缺失Mock策略（仅ITEST）
TSPEC-W008警告执行时间超过5分钟（仅STEST）
TSPEC-W009警告缺失@threshold标签（仅FTEST）
TSPEC-W010警告复杂交互场景缺失序列图（仅ITEST）
TSPEC-I001信息建议添加测试执行性能目标
TSPEC-I002信息建议添加测试数据准备文档
TSPEC-I003信息建议添加CI/CD集成说明

Validation Commands

验证命令

bash
undefined
bash
undefined

Validate single TSPEC document

验证单个TSPEC文档

python ai_dev_flow/scripts/validate_tspec.py docs/10_TSPEC/UTEST/UTEST-01_example.md
python ai_dev_flow/scripts/validate_tspec.py docs/10_TSPEC/UTEST/UTEST-01_example.md

Validate all TSPEC documents in directory

验证目录下所有TSPEC文档

python ai_dev_flow/scripts/validate_tspec.py docs/10_TSPEC/
python ai_dev_flow/scripts/validate_tspec.py docs/10_TSPEC/

Validate by type

按类型验证

python ai_dev_flow/10_TSPEC/scripts/validate_utest.py docs/10_TSPEC/UTEST/ python ai_dev_flow/10_TSPEC/scripts/validate_itest.py docs/10_TSPEC/ITEST/ python ai_dev_flow/10_TSPEC/scripts/validate_stest.py docs/10_TSPEC/STEST/ python ai_dev_flow/10_TSPEC/scripts/validate_ftest.py docs/10_TSPEC/FTEST/
python ai_dev_flow/10_TSPEC/scripts/validate_utest.py docs/10_TSPEC/UTEST/ python ai_dev_flow/10_TSPEC/scripts/validate_itest.py docs/10_TSPEC/ITEST/ python ai_dev_flow/10_TSPEC/scripts/validate_stest.py docs/10_TSPEC/STEST/ python ai_dev_flow/10_TSPEC/scripts/validate_ftest.py docs/10_TSPEC/FTEST/

Validate all TSPEC types

验证所有TSPEC类型

bash ai_dev_flow/10_TSPEC/scripts/validate_all_tspec.sh docs/10_TSPEC/
bash ai_dev_flow/10_TSPEC/scripts/validate_all_tspec.sh docs/10_TSPEC/

Quality score validation

质量分数验证

bash ai_dev_flow/10_TSPEC/scripts/validate_tspec_quality_score.sh docs/10_TSPEC/
bash ai_dev_flow/10_TSPEC/scripts/validate_tspec_quality_score.sh docs/10_TSPEC/

Validate with verbose output

启用 verbose 输出验证

python ai_dev_flow/scripts/validate_tspec.py docs/10_TSPEC/ --verbose
python ai_dev_flow/scripts/validate_tspec.py docs/10_TSPEC/ --verbose

Validate with auto-fix

启用自动修复验证

python ai_dev_flow/scripts/validate_tspec.py docs/10_TSPEC/ --auto-fix
python ai_dev_flow/scripts/validate_tspec.py docs/10_TSPEC/ --auto-fix

Cross-document validation

跨文档验证

python ai_dev_flow/scripts/validate_cross_document.py --document docs/10_TSPEC/UTEST/UTEST-01.md --auto-fix
python ai_dev_flow/scripts/validate_cross_document.py --document docs/10_TSPEC/UTEST/UTEST-01.md --auto-fix

Cumulative tagging validation

累积标签验证

python ai_dev_flow/scripts/validate_tags_against_docs.py
--artifact UTEST-01
--expected-layers brd,prd,ears,bdd,adr,sys,req,spec
--strict
undefined
python ai_dev_flow/scripts/validate_tags_against_docs.py
--artifact UTEST-01
--expected-layers brd,prd,ears,bdd,adr,sys,req,spec
--strict
undefined

Validation Workflow

验证流程

  1. Parse YAML frontmatter
  2. Check required metadata fields (document_type, artifact_type, layer)
  3. Validate tag taxonomy (tspec/utest/itest/stest/ftest, layer-10-artifact)
  4. Verify section structure (7 required sections)
  5. Validate Document Control table completeness
  6. Check SPEC Reference presence
  7. Validate element ID format (TSPEC.NN.TT.SS)
  8. Verify element type code matches document type:
    • UTEST: code 40
    • ITEST: code 41
    • STEST: code 42
    • FTEST: code 43
  9. Validate cumulative tags (8 required: @brd through @spec)
  10. Check Coverage Matrix completeness
  11. Validate I/O tables present for all test cases
  12. Check pseudocode for complex tests
  13. Verify error cases documented
  14. Calculate TASKS-Ready Score
  15. Verify file naming convention
  16. Detect deprecated patterns (TC-XXX, UT-XXX, etc.)
  17. Run type-specific validations
  18. Generate validation report
  1. 解析YAML前置元数据
  2. 检查必填元数据字段（document_type、artifact_type、layer）
  3. 验证标签分类（tspec/utest/itest/stest/ftest、layer-10-artifact）
  4. 验证章节结构（7个必填章节）
  5. 验证文档控制表完整性
  6. 检查SPEC参考是否存在
  7. 验证元素ID格式（TSPEC.NN.TT.SS）
  8. 验证元素类型代码与文档类型匹配：
    • UTEST：代码40
    • ITEST：代码41
    • STEST：代码42
    • FTEST：代码43
  9. 验证累积标签（8个必填：@brd至@spec）
  10. 检查覆盖矩阵完整性
  11. 验证所有测试用例是否包含输入输出表
  12. 检查复杂测试是否包含伪代码
  13. 验证是否记录了错误场景
  14. 计算TASKS就绪评分
  15. 验证文件命名规范
  16. 检测已弃用的格式（TC-XXX、UT-XXX等）
  17. 执行类型特定验证
  18. 生成验证报告

Auto-Fix Actions

自动修复操作

IssueAuto-Fix Action
Missing cumulative tagsAdd with upstream document reference
Invalid element ID formatConvert to TSPEC.NN.TT.SS format
Missing traceability sectionInsert from template
Missing Document Control fieldsAdd placeholder fields
Deprecated ID patternsConvert to unified format (TC-001 to TSPEC.NN.TT.01)
Wrong element type codeCorrect based on document type (UTEST=40, ITEST=41, etc.)
Missing Coverage MatrixInsert template structure
Missing TASKS-Ready ScoreCalculate and insert
问题自动修复动作
缺失累积标签添加上游文档引用的标签
无效元素ID格式转换为TSPEC.NN.TT.SS格式
缺失追溯性章节从模板插入
缺失文档控制字段添加占位符字段
已弃用的ID格式转换为统一格式（如TC-001转为TSPEC.NN.TT.01）
错误的元素类型代码根据文档类型修正（UTEST=40、ITEST=41等）
缺失覆盖矩阵插入模板结构
缺失TASKS就绪评分计算并插入

Integration

集成

  • Invoked by: doc-flow, doc-tspec (post-creation), quality-advisor
  • Feeds into: trace-check (cross-document validation)
  • Reports to: quality-advisor
  • Validates output from: doc-tspec skill
  • 调用方：doc-flow、doc-tspec（创建后）、quality-advisor
  • 输出至：trace-check（跨文档验证）
  • 报告至：quality-advisor
  • 验证输出来源：doc-tspec技能

Output Format

输出格式

TSPEC Validation Report
=======================
Document: UTEST-01_auth_service_unit.md
Type: UTEST (Unit Test)
Status: PASS/FAIL

TASKS-Ready Score: 92% (Target: >=90%) [PASS]

Cumulative Tags:
  @brd: BRD.01.01.01 [PRESENT]
  @prd: PRD.01.07.01 [PRESENT]
  @ears: EARS.01.25.01 [PRESENT]
  @bdd: BDD.01.14.01 [PRESENT]
  @adr: ADR-01 [PRESENT]
  @sys: SYS.01.26.01 [PRESENT]
  @req: REQ.01.27.01 [PRESENT]
  @spec: SPEC-01 [PRESENT]
  Tags: 8/8 [COMPLETE]

Coverage Summary:
  REQ Elements: 15/18 covered (83%)
  Target: >=90%
  Status: [BELOW TARGET]

Test Cases: 12
  Element IDs Valid: 12/12
  I/O Tables Present: 11/12
  Pseudocode Present: 10/12

Errors: 0
Warnings: 3
Info: 1

[TSPEC-W002] WARNING: Missing pseudocode for TSPEC.01.40.05
[TSPEC-W004] WARNING: Coverage percentage (83%) below target (90%)
[TSPEC-W019] WARNING: Missing I/O table for TSPEC.01.40.12
[TSPEC-I002] INFO: Consider adding test data setup documentation
TSPEC验证报告
=======================
文档：UTEST-01_auth_service_unit.md
类型：UTEST（单元测试）
状态：通过/失败

TASKS就绪评分：92%（目标：≥90%）[通过]

累积标签：
  @brd: BRD.01.01.01 [已存在]
  @prd: PRD.01.07.01 [已存在]
  @ears: EARS.01.25.01 [已存在]
  @bdd: BDD.01.14.01 [已存在]
  @adr: ADR-01 [已存在]
  @sys: SYS.01.26.01 [已存在]
  @req: REQ.01.27.01 [已存在]
  @spec: SPEC-01 [已存在]
  标签：8/8 [完整]

覆盖摘要：
  REQ元素：15/18已覆盖（83%）
  目标：≥90%
  状态：[未达目标]

测试用例：12个
  元素ID有效：12/12
  输入输出表已存在：11/12
  伪代码已存在：10/12

错误：0个
警告：3个
信息：1个

[TSPEC-W002] 警告：TSPEC.01.40.05缺失伪代码
[TSPEC-W004] 警告：覆盖率（83%）未达目标（90%）
[TSPEC-W019] 警告：TSPEC.01.40.12缺失输入输出表
[TSPEC-I002] 信息：建议添加测试数据准备文档

Related Resources

相关资源

  • TSPEC Skill: 
    .claude/skills/doc-tspec/SKILL.md
  • Naming Standards: 
    .claude/skills/doc-naming/SKILL.md
    (element IDs, element type codes)
  • Quality Advisor: 
    .claude/skills/quality-advisor/SKILL.md
  • TSPEC Index: 
    ai_dev_flow/10_TSPEC/TSPEC-00_index.md
  • Traceability Matrix Template: 
    ai_dev_flow/10_TSPEC/TSPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
  • Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  • TSPEC技能：
    .claude/skills/doc-tspec/SKILL.md
  • 命名标准：
    .claude/skills/doc-naming/SKILL.md
    （元素ID、元素类型代码）
  • 质量顾问：
    .claude/skills/quality-advisor/SKILL.md
  • TSPEC索引：
    ai_dev_flow/10_TSPEC/TSPEC-00_index.md
  • 追溯矩阵模板：
    ai_dev_flow/10_TSPEC/TSPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
  • 共享标准：
    .claude/skills/doc-flow/SHARED_CONTENT.md

Templates

模板

  • ai_dev_flow/10_TSPEC/UTEST/UTEST-MVP-TEMPLATE.md
  • ai_dev_flow/10_TSPEC/ITEST/ITEST-MVP-TEMPLATE.md
  • ai_dev_flow/10_TSPEC/STEST/STEST-MVP-TEMPLATE.md
  • ai_dev_flow/10_TSPEC/FTEST/FTEST-MVP-TEMPLATE.md
  • ai_dev_flow/10_TSPEC/UTEST/UTEST-MVP-TEMPLATE.md
  • ai_dev_flow/10_TSPEC/ITEST/ITEST-MVP-TEMPLATE.md
  • ai_dev_flow/10_TSPEC/STEST/STEST-MVP-TEMPLATE.md
  • ai_dev_flow/10_TSPEC/FTEST/FTEST-MVP-TEMPLATE.md

Quality Gates

质量门

  • ai_dev_flow/10_TSPEC/UTEST/UTEST_MVP_QUALITY_GATES.md
  • ai_dev_flow/10_TSPEC/ITEST/ITEST_MVP_QUALITY_GATES.md
  • ai_dev_flow/10_TSPEC/STEST/STEST_MVP_QUALITY_GATES.md
  • ai_dev_flow/10_TSPEC/FTEST/FTEST_MVP_QUALITY_GATES.md
  • ai_dev_flow/10_TSPEC/UTEST/UTEST_MVP_QUALITY_GATES.md
  • ai_dev_flow/10_TSPEC/ITEST/ITEST_MVP_QUALITY_GATES.md
  • ai_dev_flow/10_TSPEC/STEST/STEST_MVP_QUALITY_GATES.md
  • ai_dev_flow/10_TSPEC/FTEST/FTEST_MVP_QUALITY_GATES.md

Version History

版本历史

VersionDateChanges
1.12026-02-11Nested Folder Rule: Added Section 0 Folder Structure Validation (BLOCKING); TSPEC must be in 
docs/10_TSPEC/{TYPE}/{TYPE}-NN_{slug}/
folders; Added error codes TSPEC-E030 through TSPEC-E033
1.02026-02-08Initial release: Full TSPEC validation for UTEST/ITEST/STEST/FTEST (codes 40-43), cumulative tagging (8 required), type-specific requirements, doc-naming integration
版本日期变更
1.12026-02-11嵌套文件夹规则：新增第0节文件夹结构验证（阻塞性检查）；TSPEC必须存放在
docs/10_TSPEC/{TYPE}/{TYPE}-NN_{slug}/
文件夹中；新增错误代码TSPEC-E030至TSPEC-E033
1.02026-02-08初始版本：全面支持UTEST/ITEST/STEST/FTEST（代码40-43）的TSPEC验证、累积标签（8个必填）、类型特定要求、文档命名集成