doc-tspec-validator

Validate Test Specification (TSPEC) documents against Layer 10 schema standards.

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)

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

Schema Reference

Item	Value
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`
Layer	10
Artifact Type	TSPEC

Validation Checklist

0. Folder Structure Validation (BLOCKING)

Nested Folder Rule: ALL TSPEC documents MUST be in nested folders regardless of size.

Required Structure:

TSPEC Type	Required 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:

Code	Severity	Description
TSPEC-E030	ERROR	TSPEC not in nested folder (BLOCKING)
TSPEC-E031	ERROR	Folder name doesn't match TSPEC ID
TSPEC-E032	ERROR	File name doesn't match folder name
TSPEC-E033	ERROR	TSPEC not in correct type subdirectory

This check is BLOCKING - TSPEC must pass folder structure validation before other checks proceed.

1. Metadata Validation

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$"

2. Structure Validation

Required Sections (All TSPEC Types):

Section	Title	Required
1	Document Control	MANDATORY
2	Test Scope	MANDATORY
3	Test Case Index	MANDATORY
4	Test Case Details	MANDATORY
5	Coverage Matrix	MANDATORY
6	Traceability	MANDATORY
7	Error Cases	MANDATORY

Section Format:

## N. Title

(numbered H2 headings)

3. Document Control Required Fields

Field	Description	Required
Status	Draft/Review/Approved/Implemented	MANDATORY
Version	Semantic versioning (X.Y.Z)	MANDATORY
Date Created	YYYY-MM-DD format	MANDATORY
Last Updated	YYYY-MM-DD format	MANDATORY
Author	Test author name	MANDATORY
Component	Component/module under test	MANDATORY
SPEC Reference	SPEC-NN	MANDATORY
Coverage Target	XX%	MANDATORY
TASKS-Ready Score	`XX/100 (Target: see type-specific)`	MANDATORY

4. Test Type Element Codes

Test Type	Code	Abbreviation	TASKS-Ready Target
Unit Test	40	UTEST	>=90%
Integration Test	41	ITEST	>=85%
Smoke Test	42	STEST	100%
Functional Test	43	FTEST	>=85%

5. Element ID Format

Pattern:

TSPEC.{DOC_NUM}.{ELEM_TYPE}.{SEQ}

(4 segments, dot-separated)

Valid Element Type Codes: 40, 41, 42, 43 only

Examples:

Element ID	Valid	Test Type
`TSPEC.01.40.01`	Yes	Unit Test
`TSPEC.01.41.01`	Yes	Integration Test
`TSPEC.01.42.01`	Yes	Smoke Test
`TSPEC.01.43.01`	Yes	Functional Test
`TSPEC.01.44.01`	No	Invalid code (44 not in 40-43)
`TC-001`	No	Legacy pattern
`UT-001`	No	Legacy 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

6. Naming Compliance (doc-naming integration)

File Naming Patterns:

Pattern	Example	Document 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

7. Cumulative Tagging Requirements

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:

Notation	Format	Artifacts
Dash	TYPE-NN	ADR, SPEC, CTR
Dot	TYPE.NN.TT.SS	BRD, PRD, EARS, BDD, SYS, REQ, TSPEC

8. Test Case Format Requirements

Each test case MUST include:

markdown

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

**Category**: [Logic] | [State] | [Validation] | [Edge] | [Integration] | [Critical Path]

**Traceability**:
- @req: REQ.NN.27.XX
- @spec: SPEC-NN (Section X.Y)

**Input/Output Table**:

| Input | Expected Output | Notes |
|-------|-----------------|-------|
| `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 Condition | Expected Behavior |
|-----------------|-------------------|
| Invalid input type | Raise `TypeError` |

9. Coverage Matrix Validation

Required Format:

markdown

## Coverage Matrix

| REQ ID | REQ Title | Test IDs | Coverage |
|--------|-----------|----------|----------|
| REQ.NN.27.01 | [Title] | TSPEC.NN.40.01, TSPEC.NN.40.03 | Covered |
| REQ.NN.27.02 | [Title] | - | NOT COVERED |

**Coverage Summary**:
- Total REQ elements: [N]
- Covered: [N]
- Coverage: [XX]%

10. Type-Specific Requirements

UTEST (Unit Tests - Code 40)

Requirement	Value
TASKS-Ready Target	>=90%
Required Tags	@req, @spec
Test Categories	[Logic], [State], [Validation], [Edge]
Function Coverage	>=90%
Branch Coverage	>=80%

ITEST (Integration Tests - Code 41)

Requirement	Value
TASKS-Ready Target	>=85%
Required Tags	@ctr, @sys, @spec
Test Categories	[Integration], [Contract], [Sequence]
Sequence Diagrams	Required for complex interactions
Mock Strategy	Must be documented

STEST (Smoke Tests - Code 42)

Requirement	Value
TASKS-Ready Target	100%
Required Tags	@ears, @bdd, @req
Test Categories	[Critical Path], [Health Check], [Deployment]
Execution Time	<5 minutes total
Critical Path Coverage	100%

FTEST (Functional Tests - Code 43)

Requirement	Value
TASKS-Ready Target	>=85%
Required Tags	@sys, @threshold
Test Categories	[Functional], [Scenario], [End-to-End]
SYS Coverage	Required
Threshold References	Must include @threshold tags

Error Codes

Code	Severity	Description
TSPEC-E001	ERROR	Missing required tag 'tspec' (or type-specific: utest/itest/stest/ftest)
TSPEC-E002	ERROR	Missing required tag 'layer-10-artifact'
TSPEC-E003	ERROR	Invalid document_type value
TSPEC-E004	ERROR	Invalid architecture_approaches format (must be array)
TSPEC-E005	ERROR	Forbidden tag pattern detected
TSPEC-E006	ERROR	Missing required section
TSPEC-E007	ERROR	Multiple H1 headings detected
TSPEC-E008	ERROR	Section numbering not sequential
TSPEC-E009	ERROR	Document Control missing required fields
TSPEC-E010	ERROR	Missing Test Case Details (Section 4)
TSPEC-E011	ERROR	Invalid element type code (must be 40-43)
TSPEC-E012	ERROR	Missing cumulative tags (requires 8: @brd through @spec)
TSPEC-E013	ERROR	Invalid element ID format (not TSPEC.NN.TT.SS)
TSPEC-E014	ERROR	Missing upstream @spec tag
TSPEC-E015	ERROR	Missing Coverage Matrix (Section 5)
TSPEC-E016	ERROR	Missing SPEC Reference in Document Control
TSPEC-E017	ERROR	Deprecated ID pattern used (TC-XXX, UT-XXX, IT-XXX, ST-XXX, FT-XXX)
TSPEC-E018	ERROR	Element type code mismatch (e.g., using 40 in ITEST document)
TSPEC-E019	ERROR	Missing I/O table for test case
TSPEC-E020	ERROR	Missing traceability section
TSPEC-W001	WARNING	File name does not match format {TYPE}-NN_{slug}.md
TSPEC-W002	WARNING	Missing pseudocode for complex test case
TSPEC-W003	WARNING	TASKS-Ready Score below type-specific target
TSPEC-W004	WARNING	Coverage percentage below target
TSPEC-W005	WARNING	Missing error cases documentation
TSPEC-W006	WARNING	Missing test fixtures documentation
TSPEC-W007	WARNING	Missing mock strategy (ITEST only)
TSPEC-W008	WARNING	Execution time exceeds 5 minutes (STEST only)
TSPEC-W009	WARNING	Missing @threshold tags (FTEST only)
TSPEC-W010	WARNING	Missing sequence diagrams for complex interactions (ITEST only)
TSPEC-I001	INFO	Consider adding performance targets for test execution
TSPEC-I002	INFO	Consider adding test data setup documentation
TSPEC-I003	INFO	Consider adding CI/CD integration notes

Validation Commands

bash

# Validate single TSPEC document
python ai_dev_flow/scripts/validate_tspec.py docs/10_TSPEC/UTEST/UTEST-01_example.md

# Validate all TSPEC documents in directory
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/

# Validate all TSPEC types
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/

# Validate with verbose output
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

# Cross-document validation
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

Validation Workflow

Parse YAML frontmatter
Check required metadata fields (document_type, artifact_type, layer)
Validate tag taxonomy (tspec/utest/itest/stest/ftest, layer-10-artifact)
Verify section structure (7 required sections)
Validate Document Control table completeness
Check SPEC Reference presence
Validate element ID format (TSPEC.NN.TT.SS)
Verify element type code matches document type:
- UTEST: code 40
- ITEST: code 41
- STEST: code 42
- FTEST: code 43
Validate cumulative tags (8 required: @brd through @spec)
Check Coverage Matrix completeness
Validate I/O tables present for all test cases
Check pseudocode for complex tests
Verify error cases documented
Calculate TASKS-Ready Score
Verify file naming convention
Detect deprecated patterns (TC-XXX, UT-XXX, etc.)
Run type-specific validations
Generate validation report

Auto-Fix Actions

Issue	Auto-Fix Action
Missing cumulative tags	Add with upstream document reference
Invalid element ID format	Convert to TSPEC.NN.TT.SS format
Missing traceability section	Insert from template
Missing Document Control fields	Add placeholder fields
Deprecated ID patterns	Convert to unified format (TC-001 to TSPEC.NN.TT.01)
Wrong element type code	Correct based on document type (UTEST=40, ITEST=41, etc.)
Missing Coverage Matrix	Insert template structure
Missing TASKS-Ready Score	Calculate and insert

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

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

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

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

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

Version History

Version	Date	Changes
1.1	2026-02-11	Nested 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.0	2026-02-08	Initial release: Full TSPEC validation for UTEST/ITEST/STEST/FTEST (codes 40-43), cumulative tagging (8 required), type-specific requirements, doc-naming integration

doc-tspec-validator

NPX Install

Tags

SKILL.md Content

doc-tspec-validator

Purpose

Activation

Schema Reference

Validation Checklist

0. Folder Structure Validation (BLOCKING)

1. Metadata Validation

2. Structure Validation

3. Document Control Required Fields

4. Test Type Element Codes

5. Element ID Format

6. Naming Compliance (doc-naming integration)

7. Cumulative Tagging Requirements

8. Test Case Format Requirements

9. Coverage Matrix Validation

10. Type-Specific Requirements

UTEST (Unit Tests - Code 40)

ITEST (Integration Tests - Code 41)

STEST (Smoke Tests - Code 42)

FTEST (Functional Tests - Code 43)

Error Codes

Validation Commands

Validation Workflow

Auto-Fix Actions

Integration

Output Format

Related Resources

Templates

Quality Gates

Version History