references/tc-schema.md
TC Record Schema
A TC record is a JSON object stored at docs/TC/records/<TC-ID>/tc_record.json. Every record is validated against this schema and a state machine on every write.
Top-Level Fields
| Field | Type | Required | Notes |
|-------|------|----------|-------|
| tc_id | string | yes | Pattern: TC-NNN-MM-DD-YY-slug |
| parent_tc | string | null | no | For sub-TCs only |
| title | string | yes | 5-120 characters |
| status | enum | yes | One of: planned, in_progress, blocked, implemented, tested, deployed |
| priority | enum | yes | critical, high, medium, low |
| created | ISO 8601 | yes | UTC timestamp |
| updated | ISO 8601 | yes | UTC timestamp, refreshed on every write |
| created_by | string | yes | Author identifier (e.g., user:micha, ai:claude-opus) |
| project | string | yes | Project name (denormalized from registry) |
| description | object | yes | See below |
| files_affected | array | yes | See below |
| revision_history | array | yes | Append-only, sequential R<n> IDs |
| sub_tcs | array | no | Child TCs |
| test_cases | array | yes | Sequential T<n> IDs |
| approval | object | yes | See below |
| session_context | object | yes | See below |
| tags | array | yes | Freeform tags |
| related_tcs | array | yes | Cross-references |
| notes | string | yes | Freeform notes |
| metadata | object | yes | See below |
description
{
"summary": "string (10+ chars)",
"motivation": "string (1+ chars)",
"scope": "feature|bugfix|refactor|infrastructure|documentation|hotfix|enhancement",
"detailed_design": "string|null",
"breaking_changes": ["string", "..."],
"dependencies": ["string", "..."]
}
files_affected (array of objects)
{
"path": "src/auth.py",
"action": "created|modified|deleted|renamed",
"description": "string|null",
"lines_added": "integer|null",
"lines_removed": "integer|null"
}
revision_history (array of objects, append-only)
{
"revision_id": "R1",
"timestamp": "2026-04-05T12:34:56+00:00",
"author": "ai:claude-opus",
"summary": "Created TC record",
"field_changes": [
{
"field": "status",
"action": "set|changed|added|removed",
"old_value": "planned",
"new_value": "in_progress",
"reason": "Starting implementation"
}
]
}
Rules:
- IDs are sequential: R1, R2, R3, ... no gaps allowed.
- The first entry is always the creation event.
- Existing entries are NEVER modified or deleted.
test_cases (array of objects)
{
"test_id": "T1",
"title": "Login returns JWT for valid credentials",
"procedure": ["POST /login", "with valid creds"],
"expected_result": "200 + token in body",
"actual_result": "string|null",
"status": "pending|pass|fail|skip|blocked",
"evidence": [
{
"type": "log_snippet|screenshot|file_reference|command_output",
"description": "string",
"content": "string|null",
"path": "string|null",
"timestamp": "ISO|null"
}
],
"tested_by": "string|null",
"tested_date": "ISO|null"
}
approval
{
"approved": false,
"approved_by": "string|null",
"approved_date": "ISO|null",
"approval_notes": "string",
"test_coverage_status": "none|partial|full"
}
Consistency rule: if approved=true, both approved_by and approved_date MUST be set.
session_context
{
"current_session": {
"session_id": "string",
"platform": "claude_code|claude_web|api|other",
"model": "string",
"started": "ISO",
"last_active": "ISO|null"
},
"handoff": {
"progress_summary": "string",
"next_steps": ["string", "..."],
"blockers": ["string", "..."],
"key_context": ["string", "..."],
"files_in_progress": [
{
"path": "src/foo.py",
"state": "editing|needs_review|partially_done|ready",
"notes": "string|null"
}
],
"decisions_made": [
{
"decision": "string",
"rationale": "string",
"timestamp": "ISO"
}
]
},
"session_history": [
{
"session_id": "string",
"platform": "string",
"model": "string",
"started": "ISO",
"ended": "ISO",
"summary": "string",
"changes_made": ["string", "..."]
}
]
}
metadata
{
"project": "string",
"created_by": "string",
"last_modified_by": "string",
"last_modified": "ISO",
"estimated_effort": "trivial|small|medium|large|epic|null"
}
Registry Schema (tc_registry.json)
{
"project_name": "string",
"created": "ISO",
"updated": "ISO",
"next_tc_number": 1,
"records": [
{
"tc_id": "TC-001-...",
"title": "string",
"status": "enum",
"scope": "enum",
"priority": "enum",
"created": "ISO",
"updated": "ISO",
"path": "records/TC-001-.../tc_record.json"
}
],
"statistics": {
"total": 0,
"by_status": { "planned": 0, "in_progress": 0, "blocked": 0, "implemented": 0, "tested": 0, "deployed": 0 },
"by_scope": { "feature": 0, "bugfix": 0, "refactor": 0, "infrastructure": 0, "documentation": 0, "hotfix": 0, "enhancement": 0 },
"by_priority": { "critical": 0, "high": 0, "medium": 0, "low": 0 }
}
}
Statistics are recomputed on every registry write. Never edit them by hand.