teamspec 4.2.0 → 4.3.0

package/teamspec-core/templates/sd-template.md

@@ -1,4 +1,55 @@
-# Solution Design: `<sd-PRX-XXX-description>`
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: sd
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: SA
+artifact_type: Product Canon
+canonicity: canon
+lifecycle: permanent
+
+# === Naming ===
+id_pattern: "sd-{PRX}-{NNN}"
+filename_pattern: "sd-{PRX}-{NNN}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: product
+    pattern: "product.yml"
+    optional: false
+  - type: feature
+    pattern: "f-{PRX}-{NNN}"
+    optional: true
+
+# === Search Optimization ===
+keywords:
+  - solution design
+  - integration design
+  - system design
+  - component design
+aliases:
+  - design document
+  - technical solution
+anti_keywords:
+  - architecture decision
+  - business requirements
+  - story
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only"
+  required_sections:
+    - Overview
+    - Business Context
+    - Solution
+  optional_sections:
+    - Alternatives
+    - Risks
+---
+
+# Solution Design: `sd-{PRX}-{NNN}-{description}`
 
 > **ID:** sd-PRX-XXX  
 > **Product:** `<product-id>` (PRX)  
@@ -28,12 +79,20 @@
 
 ## 1. Overview
 
+> **Contract:** What this solution accomplishes at a glance.  
+> **Required precision:** One paragraph summary.  
+> **Not this:** Full technical details (those go in Solution Architecture).
+
 _Brief description of the solution design and what it accomplishes._
 
 ---
 
 ## 2. Business Context
 
+> **Contract:** Business driver for this design.  
+> **Required precision:** Link to Feature Canon and requirements.  
+> **Not this:** Technical rationale (that goes in Design Rationale).
+
 > Reference to Feature Canon and business requirements that drove this design.
 
 _What business need or requirement triggered this design?_

package/teamspec-core/templates/sdi-template.md

@@ -1,4 +1,53 @@
-# Solution Design Increment: `<sdi-PRX-XXX-description>`
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: sdi
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: SA
+artifact_type: Project Execution
+canonicity: project-execution
+lifecycle: project-bound
+
+# === Naming ===
+id_pattern: "sdi-{PRX}-{NNN}"
+filename_pattern: "sdi-{PRX}-{NNN}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: solution-design
+    pattern: "sd-{PRX}-{NNN}"
+    optional: false
+  - type: feature-increment
+    pattern: "fi-{PRX}-{NNN}"
+    optional: true
+
+# === Search Optimization ===
+keywords:
+  - solution design increment
+  - SDI
+  - design delta
+  - integration change
+aliases:
+  - design change proposal
+anti_keywords:
+  - architecture decision
+  - story
+  - feature behavior
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only"
+  required_sections:
+    - Overview
+    - AS-IS
+    - TO-BE
+  optional_sections:
+    - Risks
+---
+
+# Solution Design Increment: `sdi-{PRX}-{NNN}-{description}`
 
 > **ID:** sdi-PRX-XXX  
 > **Product:** `<product-id>` (PRX)  
@@ -30,12 +79,20 @@
 
 ## 1. Overview
 
+> **Contract:** Summary of this design increment.  
+> **Required precision:** What changes and why for this project.  
+> **Not this:** Full SD document (that's the Product SD).
+
 _Brief description of the solution design increment specific to this project._
 
 ---
 
 ## 2. AS-IS (Current Product SD)
 
+> **Contract:** Current production design state.  
+> **Required precision:** Copy from Product SD, do not paraphrase.  
+> **Not this:** Proposed changes (those go in TO-BE).
+
 > _Auto-populated from Product Solution Design. DO NOT EDIT unless correcting errors._
 
 _Copy relevant sections from the Product SD._
@@ -44,6 +101,10 @@ _Copy relevant sections from the Product SD._
 
 ## 3. TO-BE (Project Solution Design)
 
+> **Contract:** Proposed design after this increment.  
+> **Required precision:** Specific changes, not full restatement.  
+> **Not this:** Current state (that's AS-IS).
+
 ### 3.1 New/Changed Design Elements
 
 _Describe what the project-specific solution design includes that product design doesn't._

package/teamspec-core/templates/sprint-goal-template.md

@@ -1,6 +1,38 @@
+---
+artifact_kind: sprint-goal
+spec_version: "4.0"
+template_version: "4.0.1"
+role_owner: SM
+keywords:
+  - sprint goal
+  - sprint objective
+  - sprint commitment
+  - sprint planning output
+  - iteration goal
+  - sprint success criteria
+  - sprint focus
+  - sprint capacity
+  - committed stories
+anti_keywords:
+  - product backlog
+  - feature canon
+  - epic planning
+  - release planning
+  - retrospective
+links_required:
+  - type: story
+    pattern: "stories/S-*.md"
+  - type: sprint
+    pattern: "sprints/sprint-*/"
+completion_rules:
+  goal_rule: "Sprint goal must be one clear, measurable objective"
+  success_criteria_rule: "Must have specific, measurable success criteria"
+  story_link_rule: "Committed stories must link to story files"
+---
+
 # Sprint {N} Goal
 
-> **Template Version**: 2.0  
+> **Template Version**: 4.0.1  
 > **Last Updated**: 2026-01-07  
 > **Sprint Duration**: {YYYY-MM-DD} to {YYYY-MM-DD}  
 > **Status**: Planning | Active | Closed
@@ -15,6 +47,10 @@
 
 ## Sprint Goal
 
+> **Contract:** One clear, measurable objective for the sprint.  
+> **Required precision:** Specific outcomes that can be verified.  
+> **Not this:** Feature lists, vague themes, or multiple goals.
+
 > {One clear, measurable objective that the team commits to achieving this sprint}
 
 **Success Criteria**:
@@ -38,6 +74,10 @@
 
 ## Committed Stories
 
+> **Contract:** Stories committed for this sprint with links and status.  
+> **Required precision:** Each story must link to its dev plan and owner.  
+> **Not this:** Uncommitted backlog items or wishlist entries.
+
 | Story ID | Title | Points | Dev Plan | Owner | Status |
 |----------|-------|--------|----------|-------|--------|
 | [S-XXX](../../stories/ready-for-development/S-XXX-*.md) | {Title} | {N} | [Plan](../../dev-plans/story-XXX-tasks.md) | @{dev} | Not Started |

package/teamspec-core/templates/sprint-template.md

@@ -1,3 +1,52 @@
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: sprint
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: SM
+artifact_type: Operational
+canonicity: planning
+lifecycle: sprint-bound
+
+# === Naming ===
+id_pattern: "sprint-{N}"
+filename_pattern: "sprint-{N}/sprint-goal.md"
+
+# === Required Relationships ===
+links_required:
+  - type: project
+    pattern: "project.yml"
+    optional: false
+
+# === Search Optimization ===
+keywords:
+  - sprint
+  - iteration
+  - planning
+  - commitment
+  - capacity
+aliases:
+  - iteration
+  - cycle
+anti_keywords:
+  - feature
+  - story content
+  - requirements
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only"
+  required_sections:
+    - Sprint Goal
+    - Metadata
+    - Committed Stories
+  optional_sections:
+    - Risks
+    - Notes
+---
+
 # Sprint {N}
 
 <!--
@@ -30,6 +79,10 @@
 
 ## Sprint Goal
 
+> **Contract:** One clear, measurable objective with success criteria.  
+> **Required precision:** Specific, testable outcomes by sprint end.  
+> **Not this:** Vague aspirations or feature lists.
+
 > {One-sentence sprint objective that describes what value will be delivered}
 
 ---

package/teamspec-core/templates/sprints-index-template.md

@@ -1,6 +1,35 @@
+---
+artifact_kind: sprints-index
+spec_version: "4.0"
+template_version: "4.0.1"
+role_owner: SM
+keywords:
+  - sprints index
+  - sprint history
+  - velocity trend
+  - sprint overview
+  - sprint list
+  - iteration history
+  - sprint archive
+  - velocity tracking
+anti_keywords:
+  - active sprint details
+  - sprint planning
+  - backlog
+  - feature index
+links_required:
+  - type: sprint-goal
+    pattern: "sprints/sprint-*/sprint-goal.md"
+  - type: active-sprint
+    pattern: "sprints/active-sprint.md"
+completion_rules:
+  history_rule: "All closed sprints must be listed with velocity and status"
+  velocity_rule: "Average velocity must be calculated and updated"
+---
+
 # Sprints Index
 
-> **Template Version**: 2.0  
+> **Template Version**: 4.0.1  
 > **Last Updated**: 2026-01-07  
 > **Note**: This index provides an overview of all sprints. See [active-sprint.md](active-sprint.md) for live status.
 

package/teamspec-core/templates/story-template.md

@@ -1,3 +1,65 @@
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: story
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: FA
+artifact_type: Project Execution
+canonicality: project-execution
+lifecycle: sprint-bound
+
+# === Naming ===
+id_pattern: "s-e{EEE}-{SSS}"
+filename_pattern: "s-e{EEE}-{SSS}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: epic
+    pattern: "epic-{PRX}-{NNN}"
+    optional: false
+    note: "Epic ID embedded in filename (eXXX)"
+  - type: feature-increment
+    pattern: "fi-{PRX}-{NNN}"
+    optional: true
+    note: "Recommended for behavior changes"
+
+# === Search Optimization ===
+keywords:
+  - user story
+  - delta
+  - change request
+  - acceptance criteria
+  - sprint work
+  - execution task
+aliases:
+  - ticket
+  - work item
+  - task
+  - backlog item
+anti_keywords:
+  - full behavior
+  - production truth
+  - canon
+  - feature specification
+  - requirements document
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only; leave {TBD} if unknown"
+  id_generation: "Story ID derived from epic (eXXX) + sequence (YYY)"
+  delta_rule: "NEVER restate full feature behavior; describe ONLY what changes"
+  required_sections:
+    - User Story
+    - Linked Epic
+    - Feature Impact
+    - Acceptance Criteria
+  optional_sections:
+    - Technical Notes
+    - UX & Copy
+---
+
 # Story: `s-eXXX-YYY-description`
 
 <!-- 
@@ -18,8 +80,8 @@
   - TS-STORY-003: Acceptance Criteria required
 -->
 
-> **Template Version**: 4.0  
-> **Last Updated**: 2026-01-10
+> **Template Version**: 4.0.1  
+> **Last Updated**: 2026-01-12
 
 ---
 
@@ -73,8 +135,9 @@
 
 ## Feature Impact
 
-> Describe what this story CHANGES relative to current documented behavior.  
-> **Do NOT restate full feature behavior here.**
+> **Contract:** Describes ONLY what this story changes relative to current documented behavior.  
+> **Required precision:** Reference specific feature section; use AS-IS/TO-BE format.  
+> **Not this:** Full behavior restatement, implementation details, or technical approach.
 
 <!-- TEAMSPEC RULE: TS-STORY-002 requires Before/After (AS-IS/TO-BE) format -->
 
@@ -131,6 +194,10 @@
 
 ## Acceptance Criteria (AC)
 
+> **Contract:** Testable conditions that define "done" for this story.  
+> **Required precision:** Gherkin format (Given/When/Then) or explicit checklist.  
+> **Not this:** Vague descriptions, implementation tasks, or test scripts.
+>
 > ⚠️ **MANDATORY**: AC must be present and testable.  
 > **TEAMSPEC RULE:** TS-STORY-003 - AC required
 

package/teamspec-core/templates/storymap-template.md

@@ -1,4 +1,37 @@
 ---
+artifact_kind: storymap
+spec_version: "4.0"
+template_version: "4.0.1"
+role_owner: PO
+keywords:
+  - story map
+  - user story mapping
+  - backbone activities
+  - feature slicing
+  - story candidates
+  - release planning
+  - story prioritization
+  - mvp planning
+  - user journey
+  - feature decomposition
+anti_keywords:
+  - sprint planning
+  - technical design
+  - architecture
+  - test cases
+  - bug report
+links_required:
+  - type: epic
+    pattern: "epics/EPIC-*.md"
+  - type: feature
+    pattern: "features/F-*.md"
+completion_rules:
+  epic_link_rule: "Must link to parent Epic"
+  feature_link_rule: "Story candidates must reference Feature IDs"
+  slice_rule: "Each story candidate must belong to a feature slice"
+---
+# Story Map Document
+---
 epic_id: "[EPIC-ID]"
 epic_name: "[Epic Name]"
 goal: "[One-sentence business goal]"

package/teamspec-core/templates/ta-template.md

@@ -1,3 +1,58 @@
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: ta
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: SA
+artifact_type: Product Canon
+canonicity: canon
+lifecycle: permanent
+
+# === Naming ===
+id_pattern: "ta-{PRX}-{NNN}"
+filename_pattern: "ta-{PRX}-{NNN}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: product
+    pattern: "product.yml"
+    optional: false
+  - type: feature
+    pattern: "f-{PRX}-{NNN}"
+    optional: true
+    note: "Link to affected features"
+
+# === Search Optimization ===
+keywords:
+  - technical architecture
+  - ADR
+  - architecture decision
+  - constraints
+  - patterns
+  - technical design
+aliases:
+  - architecture document
+  - technical decision record
+anti_keywords:
+  - business requirements
+  - user behavior
+  - story
+  - feature behavior
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only; leave {TBD} if unknown"
+  required_sections:
+    - Context
+    - Decision
+    - Consequences
+  optional_sections:
+    - Alternatives Considered
+    - Related Decisions
+---
+
 # Technical Architecture: `ta-{PRX}-{NNN}-{description}`
 
 <!--
@@ -45,6 +100,10 @@
 
 ## Context
 
+> **Contract:** The technical situation requiring a decision.  
+> **Required precision:** Problem statement, constraints, forces.  
+> **Not this:** The solution itself or implementation details.
+
 > What is the problem? Why do we need to make a technical decision?
 
 [Describe the technical situation, constraints, and forces that require a decision.]
@@ -79,6 +138,10 @@
 
 ## Decision
 
+> **Contract:** The chosen option and why.  
+> **Required precision:** Clear statement of choice with primary rationale.  
+> **Not this:** Detailed implementation, code samples.
+
 > We are choosing **Option X** because...
 
 [Clear statement of the decision and primary rationale]
@@ -87,6 +150,10 @@
 
 ## Consequences
 
+> **Contract:** Trade-offs accepted by this decision.  
+> **Required precision:** Specific positive and negative impacts.  
+> **Not this:** Vague "may impact performance" statements.
+
 ### Positive
 
 - [Benefit 1]

package/teamspec-core/templates/tai-template.md

@@ -1,4 +1,53 @@
-# Technical Architecture Increment: `<tai-PRX-XXX-description>`
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: tai
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: SA
+artifact_type: Project Execution
+canonicity: project-execution
+lifecycle: project-bound
+
+# === Naming ===
+id_pattern: "tai-{PRX}-{NNN}"
+filename_pattern: "tai-{PRX}-{NNN}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: technical-architecture
+    pattern: "ta-{PRX}-{NNN}"
+    optional: false
+  - type: feature-increment
+    pattern: "fi-{PRX}-{NNN}"
+    optional: true
+
+# === Search Optimization ===
+keywords:
+  - technical architecture increment
+  - TAI
+  - architecture delta
+  - technical change
+aliases:
+  - architecture change proposal
+anti_keywords:
+  - business requirements
+  - story
+  - feature behavior
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only"
+  required_sections:
+    - Overview
+    - AS-IS
+    - TO-BE
+  optional_sections:
+    - Risks
+---
+
+# Technical Architecture Increment: `tai-{PRX}-{NNN}-{description}`
 
 > **ID:** tai-PRX-XXX  
 > **Product:** `<product-id>` (PRX)  
@@ -30,12 +79,20 @@
 
 ## 1. Overview
 
+> **Contract:** Summary of this architecture increment.  
+> **Required precision:** What changes and why for this project.  
+> **Not this:** Full TA document (that's the Product TA).
+
 _Brief description of the technical architecture increment specific to this project._
 
 ---
 
 ## 2. AS-IS (Current Product TA)
 
+> **Contract:** Current production architecture state.  
+> **Required precision:** Copy from Product TA, do not paraphrase.  
+> **Not this:** Proposed changes (those go in TO-BE).
+
 > _Auto-populated from Product Technical Architecture. DO NOT EDIT unless correcting errors._
 
 _Copy relevant sections from the Product TA._
@@ -44,6 +101,10 @@ _Copy relevant sections from the Product TA._
 
 ## 3. TO-BE (Project Technical Architecture)
 
+> **Contract:** Proposed architecture after this increment.  
+> **Required precision:** Specific changes, not full restatement.  
+> **Not this:** Current state (that's AS-IS).
+
 ### 3.1 New/Changed Architecture Elements
 
 _Describe what the project-specific architecture includes that product architecture doesn't._

package/teamspec-core/templates/tc-template.md

@@ -1,4 +1,55 @@
-# Test Cases: `<tc-fi-PRX-XXX-description>`
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: tc
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: QA
+artifact_type: Project Execution
+canonicity: project-execution
+lifecycle: project-bound
+
+# === Naming ===
+id_pattern: "tc-fi-{PRX}-{NNN}"
+filename_pattern: "tc-fi-{PRX}-{NNN}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: feature-increment
+    pattern: "fi-{PRX}-{NNN}"
+    optional: false
+  - type: feature
+    pattern: "f-{PRX}-{NNN}"
+    optional: true
+
+# === Search Optimization ===
+keywords:
+  - test case
+  - test scenario
+  - validation
+  - verification
+  - acceptance test
+aliases:
+  - test spec
+  - test script
+anti_keywords:
+  - regression test
+  - automated test code
+  - unit test
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only"
+  required_sections:
+    - Test Case Reference
+    - Test Scenarios
+  optional_sections:
+    - Test Data
+    - Automation Notes
+---
+
+# Test Cases: `tc-fi-{PRX}-{NNN}-{description}`
 
 <!-- 
   ⚠️ PROJECT-LEVEL TEST CASES
@@ -47,6 +98,10 @@
 
 ## Test Scenarios
 
+> **Contract:** Specific test cases validating FI behavior.  
+> **Required precision:** Steps, expected results, AC mapping.  
+> **Not this:** Automation code or unit tests.
+
 ### TC-001: [Title]
 
 - **Type**: Positive / Negative / Boundary