teamspec 4.2.0 → 4.3.1

package/teamspec-core/agents/AGENT_PO.md

@@ -25,6 +25,23 @@
 
 ---
 
+### 1.1 PO Quick-Lookup (LLM Retrieval Aid)
+
+| Intent | File Pattern | Notes |
+|--------|--------------|-------|
+| Product definition | `products/*/product.yml` | Use product-template.yml |
+| Product features | `products/*/features/f-PRX-*.md` | Canonical Feature Canon |
+| Product BA | `products/*/business-analysis/ba-PRX-*.md` | Production BA |
+| Product TA/SD | `products/*/technical-architecture/ta-PRX-*.md` | Production arch |
+| New project | `projects/*/project.yml` | Use project-template.yml |
+| Deployment decisions | Deployment gate checklist | PO approves sync |
+| PRX registry | `spec/4.0/registry.yml` | Prefix assignments |
+| Product lifecycle | `product.yml` status field | active/deprecated/retired |
+
+**Search tip:** For production truth, search `products/*/features/`. For proposed changes, search `projects/*/feature-increments/`.
+
+---
+
 ## 2. Inherited Rules
 
 This agent inherits all rules from [AGENT_BOOTSTRAP.md](./AGENT_BOOTSTRAP.md), including:

package/teamspec-core/agents/AGENT_QA.md

@@ -23,6 +23,22 @@
 
 ---
 
+### 1.1 QA Quick-Lookup (LLM Retrieval Aid)
+
+| Intent | File Pattern | Notes |
+|--------|--------------|-------|
+| Test cases | `qa/test-cases/tc-f-PRX-*.md` | Use tc-template.md |
+| Bug reports | `qa/bugs/BUG-*.md` | Use bug-report-template.md |
+| UAT packs | `qa/uat/uat-f-PRX-*.md` | Use uat-pack-template.md |
+| Regression sets | `products/*/qa/regression/reg-PRX-*.md` | Product-level |
+| Story ACs | `stories/S-*.md` Acceptance Criteria | Verify against FI |
+| FI TO-BE | `feature-increments/fi-PRX-*.md` TO-BE | Expected behavior |
+| Test automation | Test code in `/tests/` | E2E and integration |
+
+**Search tip:** For verification, search `qa/` directory. For expected behavior, search `feature-increments/` TO-BE sections.
+
+---
+
 ## 2. Inherited Rules
 
 This agent inherits all rules from [AGENT_BOOTSTRAP.md](./AGENT_BOOTSTRAP.md), including:

package/teamspec-core/agents/AGENT_SA.md

@@ -23,6 +23,22 @@
 
 ---
 
+### 1.1 SA Quick-Lookup (LLM Retrieval Aid)
+
+| Intent | File Pattern | Notes |
+|--------|--------------|-------|
+| New TA increment | `technical-architecture/tai-PRX-*.md` | Use tai-template.md |
+| New SD increment | `solution-designs/sdi-PRX-*.md` | Use sdi-template.md |
+| Existing TA | `products/*/technical-architecture/ta-PRX-*.md` | Product-level canonical |
+| Existing SD | `products/*/solution-designs/sd-PRX-*.md` | Product-level canonical |
+| Technical decisions | `decisions/dec-PRX-*.md` or ADRs | Use decision-log-template.md |
+| AS-IS/TO-BE analysis | Feature-Increment sections | Technical state transitions |
+| Cross-feature impact | TA/SD Impact sections | Assess dependencies |
+
+**Search tip:** For technical approach, search `technical-architecture/` and `solution-designs/` first. For decisions, check `decisions/`.
+
+---
+
 ## 2. Inherited Rules
 
 This agent inherits all rules from [AGENT_BOOTSTRAP.md](./AGENT_BOOTSTRAP.md), including:

package/teamspec-core/agents/AGENT_SM.md

@@ -23,6 +23,23 @@
 
 ---
 
+### 1.1 SM Quick-Lookup (LLM Retrieval Aid)
+
+| Intent | File Pattern | Notes |
+|--------|--------------|-------|
+| Current sprint | `sprints/active-sprint.md` | Living document |
+| Sprint goal | `sprints/sprint-N/sprint-goal.md` | Use sprint-goal-template.md |
+| Sprint history | `sprints/sprints-index.md` | All sprints index |
+| Story status | `stories/S-*.md` Status field | Track progress |
+| Velocity metrics | Sprint metrics in sprint folder | Historical data |
+| Definition of Ready | `definitions/definition-of-ready.md` | Story readiness |
+| Definition of Done | `definitions/definition-of-done.md` | Completion criteria |
+| Deployment checklist | Deployment gate section | Before PO sync |
+
+**Search tip:** For sprint operations, search `sprints/`. For story tracking, search `stories/`. Never assign priorities (PO domain).
+
+---
+
 ## 2. Inherited Rules
 
 This agent inherits all rules from [AGENT_BOOTSTRAP.md](./AGENT_BOOTSTRAP.md), including:

package/teamspec-core/agents/README.md

@@ -1,8 +1,8 @@
 # TeamSpec 4.0 Agent Prompts
 
-> **Version:** 4.0  
+> **Version:** 4.0.1  
 > **Purpose:** Predefined AI agents for TeamSpec-driven software delivery  
-> **Last Updated:** 2026-01-09
+> **Last Updated:** 2026-01-12
 
 ---
 
@@ -23,6 +23,36 @@ Each agent:
 
 ---
 
+## LLM Search Guide
+
+When searching for context, use these patterns:
+
+| If you need... | Search for | File pattern |
+|----------------|-----------|--------------|
+| Current production behavior | Product Feature | `products/**/f-{PRX}-*.md` |
+| Proposed behavior change | Feature-Increment | `projects/**/fi-{PRX}-*.md` |
+| Business context & rationale | Business Analysis | `**/ba-{PRX}-*.md` |
+| Technical constraints | Technical Architecture | `**/ta-{PRX}-*.md` |
+| Story execution details | Story | `**/s-e*-*.md` |
+| Normative rules | Registry | `spec/4.0/registry.yml` |
+
+---
+
+## Template Selection Guide
+
+| I need to... | Use Template | Owner |
+|--------------|--------------|-------|
+| Document production behavior | `feature-template.md` | FA |
+| Propose a behavior change | `feature-increment-template.md` | FA |
+| Write a development task | `story-template.md` | FA |
+| Group stories into a deliverable | `epic-template.md` | FA |
+| Record an architecture decision | `ta-template.md` | SA |
+| Track a bug | `bug-report-template.md` | QA |
+| Plan a sprint | `sprint-template.md` | SM |
+| Document business context | `business-analysis-template.md` | BA |
+
+---
+
 ## Agent Architecture
 
 ```mermaid

package/teamspec-core/copilot-instructions.md

@@ -19,6 +19,45 @@ You are an expert Agile assistant working in a **TeamSpec 4.0** enabled workspac
 
 ---
 
+## ⚠️ CRITICAL: Epistemic Safety Contract
+
+> **All agents are bound by the Epistemic Safety Contract (AGENT_BOOTSTRAP.md Section 12).**
+> **Assume your output will be legally audited. Any unsupported claim is a critical failure.**
+
+### Core Rules (NON-NEGOTIABLE)
+
+| Rule | Requirement |
+|------|-------------|
+| **ES-001** | No guessing — If not explicitly stated → `{TBD}` |
+| **ES-002** | Evidence required — Every claim needs file path + section |
+| **ES-003** | `{TBD}` is mandatory — No hedging language ("likely", "probably") |
+| **ES-004** | AS-IS is verbatim — Copy from Canon, never summarize |
+| **ES-005** | Source-locked — Only use files in workspace, no domain knowledge |
+| **ES-006** | Fail closed — STOP, output `{TBD}`, explain what's missing |
+
+### Required Output Structure
+
+All analytical or update outputs MUST include:
+
+```markdown
+### Sources Consulted
+- path/to/file.md → Section X
+
+### Unresolved Items
+- Topic A → {TBD} (missing source)
+```
+
+### Violation Severity
+
+- **Invented fact** → CRITICAL (output rejected)
+- **Missing `{TBD}`** → CRITICAL (output rejected)  
+- **Silent gap-filling** → CRITICAL (output rejected)
+- **Hedging instead of `{TBD}`** → HIGH (must correct)
+
+**Full contract:** `.teamspec/agents/AGENT_BOOTSTRAP.md` Section 12
+
+---
+
 ## What is TeamSpec?
 
 TeamSpec is an operating model that treats the **Product Canon** as the SINGLE SOURCE OF TRUTH for all production behavior. Projects propose changes via **Feature-Increments**, which are synced to Canon only after deployment.
@@ -374,14 +413,21 @@ All document templates are available in `.teamspec/templates/`:
 
 When assisting with TeamSpec:
 
-1. **Template First**: Always use templates from `.teamspec/templates/`
-2. **No Placeholders**: Never leave TBD/TODO unless explicitly asked
-3. **Markdown Strict**: Output properly formatted Markdown
-4. **Canon Reference**: Always link stories to Feature-Increments, FIs to Features
-5. **Role Awareness**: Ask which role the user is acting as if unclear
-6. **Delta Format**: Feature-Increments MUST have AS-IS/TO-BE sections
-7. **Unique IDs**: Ensure all artifacts have unique sequential IDs
-8. **PRX Consistency**: Use the product's assigned prefix everywhere
+> ⚠️ **CRITICAL: Epistemic Safety Contract applies to ALL outputs.**
+> Assume your output will be legally audited. Any unsupported claim is a critical failure.
+
+1. **Epistemic Safety First**: Every claim needs explicit source OR `{TBD}` — NO EXCEPTIONS
+2. **No Guessing**: If information is not in workspace files → `{TBD}`, never infer
+3. **Template First**: Always use templates from `.teamspec/templates/`
+4. **No Placeholders**: Never leave TBD/TODO unless information is genuinely unknown
+5. **Markdown Strict**: Output properly formatted Markdown
+6. **Canon Reference**: Always link stories to Feature-Increments, FIs to Features
+7. **Role Awareness**: Ask which role the user is acting as if unclear
+8. **Delta Format**: Feature-Increments MUST have AS-IS/TO-BE sections
+9. **Unique IDs**: Ensure all artifacts have unique sequential IDs
+10. **PRX Consistency**: Use the product's assigned prefix everywhere
+11. **Source Disclosure**: Include `### Sources Consulted` in analytical outputs
+12. **Uncertainty Disclosure**: Include `### Unresolved Items` listing all `{TBD}` items
 
 ---
 

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

@@ -1,8 +1,37 @@
+---
+artifact_kind: active-sprint
+spec_version: "4.0"
+template_version: "4.0.1"
+role_owner: SM
+keywords:
+  - active sprint
+  - current sprint
+  - sprint status
+  - sprint progress
+  - burndown
+  - sprint dashboard
+  - live sprint
+  - sprint tracker
+  - work in progress
+anti_keywords:
+  - sprint history
+  - closed sprint
+  - retrospective
+  - sprint planning
+  - backlog
+links_required:
+  - type: sprint-goal
+    pattern: "sprints/sprint-*/sprint-goal.md"
+completion_rules:
+  living_doc_rule: "This file always reflects current active sprint"
+  status_rule: "Progress summary must be kept current"
+---
+
 # Active Sprint
 
 > **Living Document**: This file always reflects the current active sprint.
 
-> **Template Version**: 2.0  
+> **Template Version**: 4.0.1  
 > **Last Updated**: 2026-01-07
 
 ---

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

@@ -1,4 +1,52 @@
-# Business Analysis Increment: `<bai-PRX-XXX-description>`
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: bai
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: BA
+artifact_type: Project Execution
+canonicity: project-execution
+lifecycle: project-bound
+
+# === Naming ===
+id_pattern: "bai-{PRX}-{NNN}"
+filename_pattern: "bai-{PRX}-{NNN}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: business-analysis
+    pattern: "ba-{PRX}-{NNN}"
+    optional: false
+  - type: feature-increment
+    pattern: "fi-{PRX}-{NNN}"
+    optional: true
+
+# === Search Optimization ===
+keywords:
+  - business analysis increment
+  - BAI
+  - business delta
+  - domain change
+aliases:
+  - business change proposal
+anti_keywords:
+  - technical design
+  - implementation
+  - story
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only"
+  required_sections:
+    - Overview
+    - Business Context
+  optional_sections:
+    - Impact Analysis
+---
+
+# Business Analysis Increment: `bai-{PRX}-{NNN}-{description}`
 
 > **ID:** bai-PRX-XXX  
 > **Product:** `<product-id>` (PRX)  
@@ -30,12 +78,20 @@
 
 ## 1. Overview
 
+> **Contract:** Brief description of the business analysis increment.  
+> **Required precision:** What this BAI adds or changes to the parent BA.  
+> **Not this:** Full BA content or implementation details.
+
 _Brief description of the business analysis increment specific to this project._
 
 ---
 
 ## 2. Business Context
 
+> **Contract:** Business problem, stakeholders, and goals for this increment.  
+> **Required precision:** Specific business justification for the change.  
+> **Not this:** Technical solutions or implementation approach.
+
 ### 2.1 Business Problem
 
 _What business problem does this address?_

package/teamspec-core/templates/bug-report-template.md

@@ -1,3 +1,54 @@
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: bug
+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: "bug-{project-id}-{NNN}"
+filename_pattern: "bug-{project-id}-{NNN}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: project
+    pattern: "project.yml"
+    optional: false
+
+# === Search Optimization ===
+keywords:
+  - bug
+  - defect
+  - issue
+  - error
+  - problem
+  - regression
+aliases:
+  - defect report
+  - issue report
+anti_keywords:
+  - feature request
+  - enhancement
+  - story
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only"
+  classification_required: true
+  required_sections:
+    - Description
+    - Steps to Reproduce
+    - Bug Classification
+  optional_sections:
+    - Screenshots
+    - Logs
+---
+
 # Bug Report: `bug-{project-id}-{NNN}-{description}`
 
 <!--
@@ -47,6 +98,10 @@
 
 ## Description
 
+> **Contract:** Clear summary of what's wrong.  
+> **Required precision:** Observable symptom, not root cause guess.  
+> **Not this:** Steps to reproduce (those go in next section).
+
 > Brief summary of the bug.
 
 [Clear, concise description of what's wrong]
@@ -92,6 +147,10 @@
 
 ## Bug Classification (MANDATORY)
 
+> **Contract:** Exactly one classification determining fix responsibility.  
+> **Required precision:** Select ONE with evidence.  
+> **Not this:** Multiple classifications or "unknown".
+
 <!-- TEAMSPEC RULE: TS-QA-002 - Exactly one must be checked -->
 
 > ⚠️ Select **exactly ONE** classification. This determines who fixes what.

package/teamspec-core/templates/business-analysis-template.md

@@ -1,3 +1,52 @@
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: ba
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: BA
+artifact_type: Product Canon
+canonicity: canon
+lifecycle: permanent
+
+# === Naming ===
+id_pattern: "ba-{PRX}-{NNN}"
+filename_pattern: "ba-{PRX}-{NNN}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: product
+    pattern: "product.yml"
+    optional: false
+
+# === Search Optimization ===
+keywords:
+  - business analysis
+  - domain analysis
+  - business context
+  - stakeholder analysis
+  - business process
+aliases:
+  - BA document
+  - business requirements
+anti_keywords:
+  - technical design
+  - implementation
+  - story
+  - feature behavior
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only"
+  required_sections:
+    - Executive Summary
+    - Business Context
+  optional_sections:
+    - Stakeholder Analysis
+    - Process Flows
+---
+
 # Business Analysis: `ba-{PRX}-{NNN}-{description}`
 
 <!--
@@ -36,6 +85,10 @@
 
 ## 1. Executive Summary
 
+> **Contract:** Problem, solution, and value proposition in brief.  
+> **Required precision:** Clear who/what/why for the business need.  
+> **Not this:** Detailed requirements or implementation scope.
+
 - **Problem Statement**: Who is the user? What is their pain?
 - **Proposed Solution**: High-level description.
 - **Value**: Why are we doing this? (Revenue, Compliance, UX).
@@ -44,6 +97,10 @@
 
 ## 2. Scope
 
+> **Contract:** Explicit boundaries of what is and is not included.  
+> **Required precision:** Specific inclusions and exclusions.  
+> **Not this:** Feature details or implementation approach.
+
 ### In Scope
 
 - [Feature 1]

package/teamspec-core/templates/decision-log-template.md

@@ -1,3 +1,55 @@
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: decision
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: PO
+artifact_type: Product Canon
+canonicity: canon
+lifecycle: permanent
+
+# === Naming ===
+id_pattern: "dec-{PRX}-{NNN}"
+filename_pattern: "dec-{PRX}-{NNN}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: product
+    pattern: "product.yml"
+    optional: false
+  - type: feature
+    pattern: "f-{PRX}-{NNN}"
+    optional: false
+    note: "Must link to affected features"
+
+# === Search Optimization ===
+keywords:
+  - decision
+  - business decision
+  - rationale
+  - scope decision
+  - priority decision
+aliases:
+  - decision record
+  - decision log entry
+anti_keywords:
+  - technical architecture
+  - implementation
+  - story
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only"
+  required_sections:
+    - Context
+    - Decision
+    - Impact
+  optional_sections:
+    - Alternatives Considered
+---
+
 # Decision: `dec-{PRX}-{NNN}-{description}`
 
 <!--
@@ -49,6 +101,12 @@
 
 ## Context
 
+> **Contract:** Business context and constraints that led to this decision.  
+> **Required precision:** Specific situation, stakeholders, and drivers.  
+> **Not this:** The decision itself or technical implementation.
+
+## Context
+
 _What situation or problem prompted this decision?_
 
 [Describe the business situation, trigger event, or problem that requires a decision.]

package/teamspec-core/templates/dev-plan-template.md

@@ -1,3 +1,50 @@
+---
+# === LLM Retrieval Metadata ===
+artifact_kind: devplan
+spec_version: "4.0"
+template_version: "4.0.1"
+
+# === Ownership ===
+role_owner: DEV
+artifact_type: Project Execution
+canonicity: project-execution
+lifecycle: sprint-bound
+
+# === Naming ===
+id_pattern: "dp-e{EEE}-s{SSS}"
+filename_pattern: "dp-e{EEE}-s{SSS}-{description}.md"
+
+# === Required Relationships ===
+links_required:
+  - type: story
+    pattern: "s-e{EEE}-{SSS}"
+    optional: false
+
+# === Search Optimization ===
+keywords:
+  - dev plan
+  - development plan
+  - implementation plan
+  - task breakdown
+aliases:
+  - implementation approach
+  - technical plan
+anti_keywords:
+  - story
+  - feature
+  - requirements
+
+# === Generation Contract ===
+completion_rules:
+  placeholders: "Fill {braces} only"
+  required_sections:
+    - Metadata
+    - Tasks
+  optional_sections:
+    - Dependencies
+    - Risks
+---
+
 # Dev Plan: `dp-e{EEE}-s{SSS}-{description}`
 
 <!--
@@ -30,6 +77,10 @@
 
 ## Metadata
 
+> **Contract:** Key identifiers and story linkage for this dev plan.  
+> **Required precision:** Story ID, owner, dates, and status must be filled.  
+> **Not this:** Implementation details or requirements.
+
 | Field | Value |
 |-------|-------|
 | **Dev Plan ID** | dp-e{EEE}-s{SSS} |