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

Validation Checklist

0. Folder Structure Validation (BLOCKING)

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

Required Structure:

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.A_audit_report_v001.md
│   │   ├── 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:

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

1. Metadata Validation

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 (Individual Test Type TSPECs – UTEST/ITEST/STEST/FTEST/PTEST/SECTEST):

Note: Error Cases are embedded within Section 4 (Test Case Details), not a separate section.

Section Format: ## N. Title (numbered H2 headings)

3. Document Control Required Fields

4. Test Type Element Codes

5. Element ID Format

Pattern: TSPEC.{DOC_NUM}.{ELEM_TYPE}.{SEQ} (4 segments, dot-separated)

Valid Element Type Codes: 40, 41, 42, 43, 44, 45

Examples:

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:

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):

@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):

@ctr: CTR-NN

Tag Format Convention:

8. Test Case Format Requirements

Each test case MUST include:

### 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:

## 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)

ITEST (Integration Tests – Code 41)

STEST (Smoke Tests – Code 42)

FTEST (Functional Tests – Code 43)

Error Codes

Validation Commands

# Validate by type
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_utest.py docs/10_TSPEC/UTEST/
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_itest.py docs/10_TSPEC/ITEST/
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_stest.py docs/10_TSPEC/STEST/
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_ftest.py docs/10_TSPEC/FTEST/
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_ptest.py docs/10_TSPEC/PTEST/
python ai_dev_ssd_flow/10_TSPEC/scripts/validate_sectest.py docs/10_TSPEC/SECTEST/

# Validate all TSPEC types
bash ai_dev_ssd_flow/10_TSPEC/scripts/validate_all_tspec.sh docs/10_TSPEC/

# Quality score validation
bash ai_dev_ssd_flow/10_TSPEC/scripts/validate_tspec_quality_score.sh docs/10_TSPEC/

# Cross-document validation
python ai_dev_ssd_flow/scripts/validate_cross_document.py --document docs/10_TSPEC/UTEST/UTEST-01.md --auto-fix

# Cumulative tagging validation
python ai_dev_ssd_flow/scripts/validate_tags_against_docs.py \
  --artifact UTEST-01 \
  --expected-layers brd,prd,ears,bdd,adr,sys,req,spec \
  --strict

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 (6 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

Auto-Fix Actions

Integration

• Invoked by: doc-flow, doc-tspec (post-creation), quality-advisor
• Invoked by: doc-flow, doc-tspec (post-creation), quality-advisor, doc-tspec-audit
• 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_ssd_flow/10_TSPEC/TSPEC-00_index.md
• Traceability Matrix Template: ai_dev_ssd_flow/10_TSPEC/TSPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
• Shared Standards: .claude/skills/doc-flow/SHARED_CONTENT.md

Templates

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

Quality Gates

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

Version History