teamspec 3.2.0

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

@@ -0,0 +1,194 @@
+# ADR-XXX: [Decision Title]
+
+<!-- 
+  ⚠️ ADR RULES
+  
+  Architecture Decision Records document technical decisions.
+  
+  RULES:
+  1. ADRs link to features they affect
+  2. ADRs link to business decisions that triggered them
+  3. SA does NOT update Feature Canon directly - ADRs inform FA
+  4. If behavior is affected, FA must review Feature Canon
+  
+  TEAMSPEC RULES ENFORCED:
+  - TS-ADR-001: ADR required for architecture-impacting changes
+  - TS-ADR-002: ADR must link to affected features
+-->
+
+> **Template Version**: 2.0  
+> **Last Updated**: 2026-01-07
+
+---
+
+**Document Owner:** SA (Solution Architect)  
+**Artifact Type:** Technical Decision (Canonical)  
+**Lifecycle:** Permanent, versioned
+
+---
+
+## Metadata
+
+| Field | Value |
+| :--- | :--- |
+| **ADR ID** | ADR-XXX |
+| **Status** | Proposed / Accepted / Deprecated / Superseded |
+| **Date** | YYYY-MM-DD |
+| **Author** | [SA Name] |
+| **Superseded By** | [ADR-YYY if applicable] |
+
+---
+
+## Context
+
+> What is the problem? Why do we need to make a decision?
+
+[Describe the technical situation, constraints, and forces that require a decision.]
+
+---
+
+## Options Considered
+
+### Option 1: [Option Name]
+
+**Description**: [Brief description]
+
+**Pros**:
+- [Pro 1]
+- [Pro 2]
+
+**Cons**:
+- [Con 1]
+- [Con 2]
+
+### Option 2: [Option Name]
+
+**Description**: [Brief description]
+
+**Pros**:
+- [Pro 1]
+
+**Cons**:
+- [Con 1]
+
+---
+
+## Decision
+
+> We are choosing **Option X** because...
+
+[Clear statement of the decision and primary rationale]
+
+---
+
+## Consequences
+
+### Positive
+
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+
+- [Trade-off 1]
+- [Trade-off 2]
+
+---
+
+## Related Decisions
+
+<!-- TEAMSPEC RULE: Link to business decisions that triggered this ADR -->
+
+| Decision ID | Decision Title | Relationship |
+|-------------|----------------|--------------|
+| [DEC-XXX](../decisions/DEC-XXX-*.md) | [Title] | Triggered by / Related to |
+
+> If this ADR was triggered by a business decision, link it here.
+
+---
+
+## Affected Features
+
+<!-- TEAMSPEC RULE: TS-ADR-002 - ADR must link to features -->
+
+> ⚠️ If this decision affects user-observable behavior, FA must review Feature Canon.
+
+| Feature ID | Feature Name | Impact | Canon Review Needed? |
+|------------|--------------|--------|---------------------|
+| [F-XXX](../features/F-XXX-name.md) | [Name] | [How this affects behavior] | Yes / No |
+
+---
+
+## Behavior Impact Assessment
+
+> ⚠️ SA provides technical facts. FA translates to Feature Canon behavior.
+
+### Does this ADR affect user-observable behavior?
+
+- [ ] **No** — Internal/technical change only (no Canon update needed)
+- [ ] **Yes** — Behavior implications described below
+
+### Behavior Implications (if Yes)
+
+| Technical Decision | Behavior Implication | FA Action |
+|--------------------|---------------------|-----------|
+| [e.g., Rate limit: 100 req/min] | [e.g., System rejects excess requests] | FA adds to Canon |
+
+> **Workflow:**
+> 1. SA creates ADR with technical constraints
+> 2. ADR may imply behavior constraints
+> 3. FA incorporates constraints into Feature Canon
+> 4. FA owns the behavioral wording
+
+---
+
+## Examples of Behavior-Impacting Decisions
+
+✅ **Include in Feature Impact** (FA must review Canon):
+- Changing how errors are reported to users
+- Adding/removing functionality constraints
+- Changing performance characteristics users observe
+- Changing access control or permissions
+
+❌ **Usually no Feature Impact**:
+- Internal refactoring (no user-observable change)
+- Technology stack decisions (if behavior unchanged)
+- Database optimization (if behavior unchanged)
+
+---
+
+## Documentation Trail
+
+This ADR is referenced in Feature Canon Change Log when it affects documented behavior:
+
+> ADR-XXX: [Title] — Added [feature capability / constraint]
+
+This maintains traceability between architecture and product behavior.
+
+---
+
+## Implementation Notes
+
+_Technical details for DEV team._
+
+- [Implementation note 1]
+- [Implementation note 2]
+
+---
+
+## Review & Approval
+
+| Role | Name | Status | Date |
+|------|------|--------|------|
+| SA (Author) | [Name] | ✅ | YYYY-MM-DD |
+| Tech Lead | [Name] | ⏳ | |
+| FA (if behavior affected) | [Name] | ⏳ | |
+
+---
+
+## Linter Rules Enforced
+
+| Rule | Description |
+|------|-------------|
+| TS-ADR-001 | ADR required for architecture-impacting changes |
+| TS-ADR-002 | ADR must link to affected features |

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

@@ -0,0 +1,188 @@
+# Bug: [Title]
+
+<!-- 
+  ⚠️ BUG CLASSIFICATION IS MANDATORY
+  
+  When reporting bugs, you MUST classify whether the issue is:
+  - Implementation defect (code doesn't match Canon)
+  - Feature Canon wrong (Canon doesn't match business intent)
+  - Undocumented behavior (neither covers this case)
+  
+  Classification determines who fixes what.
+  
+  TEAMSPEC RULES ENFORCED:
+  - TS-QA-002: Bug classification required (exactly one)
+-->
+
+> **Template Version**: 2.0  
+> **Last Updated**: 2026-01-07
+
+---
+
+**Document Owner:** QA (QA Engineer)  
+**Artifact Type:** Defect Report  
+**Lifecycle:** Open → Resolved → Closed
+
+---
+
+## Metadata
+
+| Field | Value |
+| :--- | :--- |
+| **Bug ID** | BUG-XXX |
+| **Severity** | Critical / High / Medium / Low |
+| **Priority** | P1 / P2 / P3 / P4 |
+| **Environment** | Staging / Dev / Production |
+| **Version** | [Build Number] |
+| **Reporter** | [Name] |
+| **Date Reported** | YYYY-MM-DD |
+| **Status** | Open / In Progress / Resolved / Closed |
+
+---
+
+## Description
+
+> Brief summary of the bug.
+
+[Clear, concise description of what's wrong]
+
+---
+
+## Steps to Reproduce
+
+1. Go to ...
+2. Click ...
+3. Enter ...
+4. Observe ...
+
+---
+
+## Expected Result
+
+> What should happen (reference Feature Canon if applicable).
+
+**Feature Canon Reference:** [F-XXX](../../features/F-XXX-name.md), Section: [Section Name]
+
+[What the system should do according to Feature Canon]
+
+---
+
+## Actual Result
+
+> What actually happened.
+
+[What the system actually does]
+
+---
+
+## Evidence
+
+> Attach Screenshots/Logs/Videos
+
+- [ ] Screenshot attached
+- [ ] Console logs attached
+- [ ] Network trace attached
+
+---
+
+## Bug Classification (MANDATORY)
+
+<!-- TEAMSPEC RULE: TS-QA-002 - Exactly one must be checked -->
+
+> ⚠️ Select **exactly ONE** classification. This determines who fixes what.
+
+### [ ] Implementation Defect
+
+**Definition:** Code doesn't match Feature Canon documentation.
+
+- **Evidence:** Feature Canon says [X], system does [Y]
+- **Fix:** DEV fixes code to match Canon
+- **Canon Update:** Not required
+
+### [ ] Feature Canon Wrong
+
+**Definition:** Feature Canon doesn't match actual business intent.
+
+- **Evidence:** Business expects [X], Canon says [Y]
+- **Fix:** FA updates Feature Canon, then DEV updates code if needed
+- **Canon Update:** Required
+
+### [ ] Undocumented Behavior
+
+**Definition:** Neither code nor Feature Canon covers this case.
+
+- **Evidence:** [Scenario] is not documented anywhere
+- **Fix:** FA clarifies with BA, updates Canon, then DEV implements
+- **Canon Update:** Required
+
+---
+
+## Classification Decision Tree
+
+```
+Is the behavior documented in Feature Canon?
+├── YES → Does code match Canon?
+│   ├── YES → Not a bug (or Canon is wrong → "Feature Canon Wrong")
+│   └── NO → "Implementation Defect"
+└── NO → "Undocumented Behavior"
+```
+
+---
+
+## Resolution Actions by Classification
+
+| Classification | Who Fixes | Action |
+|----------------|-----------|--------|
+| Implementation Defect | DEV | Fix code to match Canon |
+| Feature Canon Wrong | FA → DEV | FA updates Canon; DEV updates code if needed |
+| Undocumented Behavior | FA + BA → DEV | FA clarifies with BA; updates Canon; DEV implements |
+
+---
+
+## Feature Reference
+
+| Feature | Section | Expected Behavior |
+|---------|---------|-------------------|
+| [F-XXX](../../features/F-XXX-name.md) | [Section] | [Brief description from Canon] |
+
+---
+
+## Related Stories / Bugs
+
+| ID | Type | Relationship |
+|----|------|--------------|
+| [S-XXX] | Story | Introduced behavior |
+| [BUG-YYY] | Bug | Related issue |
+
+---
+
+## Resolution
+
+**Resolved By:** ________________  
+**Resolution Date:** YYYY-MM-DD  
+**Resolution Type:** Code Fix / Canon Update / Not a Bug / Duplicate  
+**Fix Version:** [Build Number]
+
+**Resolution Notes:**
+
+[How the bug was fixed]
+
+---
+
+## Verification
+
+**Verified By:** ________________  
+**Verification Date:** YYYY-MM-DD  
+**Verification Environment:** [Environment]
+
+- [ ] Bug no longer reproduces
+- [ ] Feature Canon is accurate
+- [ ] Regression tests added
+
+---
+
+## Linter Rules Enforced
+
+| Rule | Description |
+|------|-------------|
+| TS-QA-002 | Bug classification required (exactly one) |

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

@@ -0,0 +1,164 @@
+# Business Analysis Document: [Feature Name]
+
+<!-- 
+  ⚠️ THIS IS A PLANNING ARTIFACT, NOT SOURCE OF TRUTH
+  
+  This Business Analysis document captures analysis and decisions
+  during the planning phase.
+  
+  SOURCE OF TRUTH:
+  - For current system behavior → Feature Canon (/features/F-XXX.md)
+  - For business decisions → Decision Log (/decisions/DEC-XXX.md)
+  
+  This document becomes HISTORICAL after Feature Canon is created.
+-->
+
+> **Template Version**: 2.0  
+> **Last Updated**: 2026-01-07
+
+---
+
+**Document Owner:** BA (Business Analyst)  
+**Artifact Type:** Planning (Not Source of Truth)  
+**Lifecycle:** Historical after Feature Canon creation
+
+| Metadata | Details |
+| :--- | :--- |
+| **Status** | Draft / In Review / Approved |
+| **Owner** | [BA Name] |
+| **Stakeholders** | [Names] |
+| **Created** | YYYY-MM-DD |
+
+---
+
+## 1. Executive Summary
+
+- **Problem Statement**: Who is the user? What is their pain?
+- **Proposed Solution**: High-level description.
+- **Value**: Why are we doing this? (Revenue, Compliance, UX).
+
+---
+
+## 2. Scope
+
+### In Scope
+
+- [Feature 1]
+- [Feature 2]
+
+### Out of Scope (Non-Goals)
+
+- [Feature 3]
+- [Migration of X]
+
+---
+
+## 3. Related Feature Canon
+
+> ⚠️ Link to Feature Canon files created from this analysis.
+> Once features are created, the Feature Canon is authoritative.
+> This document is retained for historical context only.
+
+| Feature ID | Feature Name | Status | Link |
+|------------|--------------|--------|------|
+| [F-XXX](../features/F-XXX-name.md) | [Feature Name] | Draft / Active | |
+
+---
+
+## 4. Business Process
+
+### Current State (As-Is)
+
+> Describe how users solve the problem today.
+
+### Future State (To-Be)
+
+> Describe the new workflow. This becomes the Feature Canon "Current Behavior" after implementation.
+
+---
+
+## 5. User Journeys / Personas
+
+| Persona | Journey | Goal |
+|---------|---------|------|
+| [Persona 1] | [Action sequence] | [What they achieve] |
+| [Persona 2] | [Action sequence] | [What they achieve] |
+
+---
+
+## 6. Business Rules & Logic
+
+> These business rules will be documented in the Feature Canon as BR-XXX references.
+
+| Rule ID | Description | Context |
+|---------|-------------|---------|
+| BR-001 | [Rule description] | [When it applies] |
+| BR-002 | [Rule description] | [When it applies] |
+
+---
+
+## 7. Data & Reporting Requirements
+
+- **Data Captured**: [Fields]
+- **Reporting Needs**: [Reports needed]
+
+---
+
+## 8. Risks & Constraints
+
+### Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| [Risk 1] | Low/Med/High | Low/Med/High | [Mitigation] |
+
+### Constraints
+
+- **Timeline**: [Deadlines]
+- **Budget**: [Budget constraints]
+- **Technical**: [Legacy systems, integrations]
+
+---
+
+## 9. Success Metrics (KPIs)
+
+| Metric | Target | Measurement Method |
+|--------|--------|-------------------|
+| [Metric 1] | [Target value] | [How measured] |
+| [Metric 2] | [Target value] | [How measured] |
+
+---
+
+## 10. Decisions Made
+
+> Business decisions from this analysis should be logged in /decisions/
+
+| Decision ID | Summary | Link |
+|-------------|---------|------|
+| [DEC-XXX](../decisions/DEC-XXX-*.md) | [Decision summary] | |
+
+---
+
+## Document Lifecycle
+
+> ⚠️ **IMPORTANT**: This document is a **planning artifact**.
+> 
+> After Feature Canon is established and updated through story implementation:
+> - This document becomes **historical reference** only
+> - The **Feature Canon** is the source of truth for current behavior
+> - Do NOT use this document to understand how the system works today
+> 
+> If you need to know what the system does now, read `/features/F-XXX-name.md`
+
+### Status Transitions
+
+| Status | Meaning |
+|--------|---------|
+| Draft | Analysis in progress |
+| In Review | Stakeholder review |
+| Approved | Ready for Feature Canon creation |
+| **Superseded** | Feature Canon is now authoritative |
+
+**Current Status:** Draft  
+**Superseded By:** [F-XXX](../features/F-XXX-name.md) (when applicable)  
+**Superseded Date:** ________________