teamspec 3.2.0

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

@@ -0,0 +1,216 @@
+# DEC-XXX: [Decision Title]
+
+<!-- 
+  ⚠️ DECISION LOG RULES
+  
+  Business decisions must be logged and linked to affected features.
+  
+  RULES:
+  1. Decisions must link to at least one feature
+  2. BA owns business decisions
+  3. Decisions that affect scope require feature review
+  4. Cross-feature decisions require SA acknowledgment
+  
+  TEAMSPEC RULES ENFORCED:
+  - TS-DEC-001: Decision must link to features
+-->
+
+> **Template Version**: 2.0  
+> **Last Updated**: 2026-01-07
+
+---
+
+**Document Owner:** BA (Business Analyst)  
+**Artifact Type:** Business Decision (Canonical)  
+**Lifecycle:** Permanent
+
+---
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Decision ID** | DEC-XXX |
+| **Date Proposed** | YYYY-MM-DD |
+| **Date Confirmed** | YYYY-MM-DD (or "Pending") |
+| **Decision Owner(s)** | [Stakeholder Name(s)] |
+| **Facilitator** | [BA Name] |
+| **Status** | Proposed / Confirmed / Superseded |
+| **Type** | Reversible / Costly / Irreversible |
+| **Severity** | Minor / Major / Critical |
+| **Scope** | Feature / Cross-Feature / Product |
+| **Superseded By** | [DEC-YYY if applicable] |
+
+---
+
+## Context
+
+_What situation or problem prompted this decision?_
+
+[Describe the business situation, trigger event, or problem that requires a decision.]
+
+**Background**:
+- [Context point 1]
+- [Context point 2]
+
+**Stakeholders Involved**:
+- [Name/Role]
+- [Name/Role]
+
+---
+
+## Decision
+
+_What did we decide? State explicitly and unambiguously._
+
+**Decision Statement**:
+
+[Clear, action-oriented statement of what was decided.]
+
+**In Scope** (as a result of this decision):
+- [ ] [Capability/feature/behavior 1]
+- [ ] [Capability/feature/behavior 2]
+
+**Out of Scope** (explicitly excluded):
+- [ ] [What we explicitly chose NOT to do]
+- [ ] [Deferred items]
+
+---
+
+## Impacted Features
+
+<!-- TEAMSPEC RULE: TS-DEC-001 - Decision must link to features -->
+
+> ⚠️ At least one feature must be linked.
+> If this decision doesn't impact any feature, it may not need to be logged.
+
+| Feature ID | Feature Name | Impact Description |
+|------------|--------------|-------------------|
+| [F-XXX](../features/F-XXX-name.md) | [Feature Name] | [Scoped in / Scoped out / Behavior changed / Priority set] |
+
+---
+
+## Alternatives Considered
+
+### Option 1: [Alternative Name]
+
+**Description**: [Brief description]
+
+**Pros**:
+- [Pro 1]
+- [Pro 2]
+
+**Cons**:
+- [Con 1]
+- [Con 2]
+
+**Why Rejected**: [Reason]
+
+### Option 2: [Alternative Name]
+
+**Description**: [Brief description]
+
+**Pros**:
+- [Pro 1]
+
+**Cons**:
+- [Con 1]
+
+**Why Rejected**: [Reason]
+
+---
+
+## Consequences
+
+### Positive Consequences
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative Consequences (Trade-offs)
+- [Trade-off 1]
+- [Trade-off 2]
+
+### Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| [Risk 1] | Low/Med/High | Low/Med/High | [Mitigation] |
+
+---
+
+## Reversal Cost
+
+_What would it cost to reverse this decision later?_
+
+**Effort**: [Time estimate]  
+**Cost**: [Financial or resource cost]  
+**Risk**: [Technical debt, user impact]
+
+**Reversal Difficulty**: Low / Medium / High / Irreversible
+
+---
+
+## Architecture Acknowledgment
+
+> **Required if**: Type = `Irreversible` OR Scope = `Cross-Feature` / `Product`
+
+| Field | Value |
+|-------|-------|
+| **Acknowledged By** | [SA Name] |
+| **Date** | YYYY-MM-DD |
+| **Assessment** | No Impact / Requires ADR / Approved |
+| **ADR Reference** | [ADR-XXX](../adr/ADR-XXX-*.md) (if required) |
+
+**Architecture Notes**:
+[SA assessment of technical implications]
+
+---
+
+## Confirmation Record
+
+_Stakeholder confirmation that decision is accurate and approved._
+
+| Stakeholder | Role | Confirmed? | Date | Notes |
+|-------------|------|------------|------|-------|
+| [Name] | [Role] | ✅ / ⏳ / ❌ | YYYY-MM-DD | |
+
+**Confirmation Method**: [Email / Meeting / Async]  
+**Review Window**: [X days from Date Proposed]
+
+---
+
+## References
+
+### Business Analysis
+
+| Document | Link | Relevant Section |
+|----------|------|------------------|
+| [BA Title] | [Link] | [Section] |
+
+### Related Stories (if applicable)
+
+| Story ID | Story Title | Relationship |
+|----------|-------------|--------------|
+| [S-XXX](../stories/*/S-XXX-*.md) | [Title] | Created from this decision |
+
+### Related Decisions
+
+| Decision ID | Relationship |
+|-------------|--------------|
+| [DEC-YYY] | Depends on / Superseded by / Related to |
+
+---
+
+## Change Log
+
+| Date | Change | Author |
+|------|--------|--------|
+| YYYY-MM-DD | Initial decision recorded | [Name] |
+
+---
+
+## Linter Rules Enforced
+
+| Rule | Description |
+|------|-------------|
+| TS-DEC-001 | Decision must link to at least one feature |

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

@@ -0,0 +1,269 @@
+# F-XXX: [Feature Name]
+
+<!-- 
+  ⚠️ FEATURE CANON RULES
+  
+  This Feature file is the SOURCE OF TRUTH for system behavior.
+  
+  RULES:
+  1. Implementation-agnostic (describe WHAT, not HOW)
+  2. No technical implementation details
+  3. Business rules use BR-XXX format
+  4. Change Log is append-only
+  
+  TEAMSPEC RULES ENFORCED:
+  - TS-FEAT-001: Feature must have unique ID
+  - TS-FEAT-002: All required sections must be present
+  - TS-FEAT-003: Feature ID must be unique
+-->
+
+> **Template Version**: 2.0  
+> **Last Updated**: 2026-01-07
+
+---
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Feature ID** | F-XXX |
+| **Status** | Planned / Active / Deprecated / Retired |
+| **Owner** | [BA creates, FA maintains behavior] |
+| **Created** | YYYY-MM-DD |
+| **Last Updated** | YYYY-MM-DD |
+
+**Document Ownership:**
+- **BA owns:** Purpose, Business Value, Scope (In/Out)
+- **FA owns:** Current Behavior, Business Rules, Edge Cases
+
+---
+
+## Section Checklist
+
+<!-- TEAMSPEC RULE: TS-FEAT-002 - All sections required -->
+
+| Section | Status | Notes |
+|---------|--------|-------|
+| Purpose | [ ] | Why this feature exists |
+| Business Value | [ ] | Impact and success metrics |
+| Scope (In) | [ ] | What's included |
+| Scope (Out) | [ ] | What's excluded |
+| Actors/Personas | [ ] | Who uses it |
+| Current Behavior | [ ] | Primary behavior (authoritative) |
+| Business Rules | [ ] | BR-XXX format |
+| Edge Cases | [ ] | Known exceptions |
+| Non-Goals | [ ] | Explicitly excluded capabilities |
+| Change Log | [ ] | Story references |
+
+> ⚠️ Feature cannot be referenced by stories until all sections are complete.
+
+---
+
+## Governing Decisions
+
+_Business decisions that shaped this feature's scope, behavior, or priority._
+
+| Decision ID | Summary | Impact on This Feature |
+|-------------|---------|------------------------|
+| [DEC-XXX](../decisions/DEC-XXX-*.md) | [One-line decision summary] | [Scoped in / Scoped out / Behavior changed / Priority set] |
+
+---
+
+## Purpose
+
+> **Owner:** BA (Business Analyst)
+
+_One to three sentences describing what this feature enables users to do._
+
+[What capability does this provide? What user need does it address?]
+
+---
+
+## Business Value
+
+> **Owner:** BA (Business Analyst)
+
+_Why this feature matters to the business._
+
+- **User Impact**: [How does this improve user experience?]
+- **Business Impact**: [Revenue, efficiency, compliance, etc.]
+- **Success Metrics**: [How do we measure success?]
+
+---
+
+## In Scope
+
+> **Owner:** BA (Business Analyst)
+
+_Explicit boundaries of what this feature includes._
+
+- [ ] [Capability 1]
+- [ ] [Capability 2]
+- [ ] [Capability 3]
+
+---
+
+## Out of Scope
+
+> **Owner:** BA (Business Analyst)
+
+_Explicit boundaries of what this feature does NOT include. Prevents scope creep._
+
+- [ ] [Excluded capability 1]
+- [ ] [Excluded capability 2]
+
+---
+
+## Actors / Personas
+
+> **Owner:** BA (Business Analyst)
+
+_Who uses this feature and what are their goals._
+
+| Persona | Description | Primary Goals |
+|---------|-------------|---------------|
+| [Persona 1] | [Brief description] | [What they want to achieve] |
+| [Persona 2] | [Brief description] | [What they want to achieve] |
+
+---
+
+## Current Behavior
+
+> **Owner:** FA (Functional Analyst)
+> 
+> ⚠️ **AUTHORITATIVE SECTION**: This describes what the system does TODAY.  
+> Update this section whenever a story changes observable behavior.
+
+### [Behavior Area 1]
+
+[Describe current system behavior in precise, testable terms.]
+
+### [Behavior Area 2]
+
+[Describe current system behavior.]
+
+### User Flows
+
+1. User does X
+2. System responds with Y
+3. User sees Z
+
+### Edge Cases & Error Handling
+
+| Condition | System Response |
+|-----------|-----------------|
+| [Edge case 1] | [Response] |
+| [Error condition] | [Error handling] |
+
+---
+
+## Business Rules
+
+> **Owner:** FA (Functional Analyst)
+
+_Logic that governs this feature's behavior._
+
+| Rule ID | Rule Description | Applies When |
+|---------|------------------|--------------|
+| BR-XXX-001 | [Rule description] | [Context] |
+| BR-XXX-002 | [Rule description] | [Context] |
+
+---
+
+## Roles & Permissions
+
+_Who can do what within this feature._
+
+| Role | Permissions |
+|------|-------------|
+| [Role 1] | [Can do X, Y, Z] |
+| [Role 2] | [Can do A, B] |
+| [Role 3] | [View only] |
+
+---
+
+## Non-Functional Notes
+
+_Performance, security, accessibility, and other quality requirements._
+
+- **Performance**: [Response time expectations, throughput]
+- **Security**: [Authentication, authorization, data protection]
+- **Accessibility**: [WCAG level, specific requirements]
+- **Availability**: [Uptime requirements]
+
+---
+
+## Non-Goals
+
+> **Owner:** BA (Business Analyst)
+
+_Capabilities explicitly NOT included in this feature. Different from Out of Scope—these are things that might seem related but are deliberately excluded._
+
+- [Non-goal 1]: [Why excluded]
+- [Non-goal 2]: [Why excluded]
+
+---
+
+## Open Questions
+
+_Unresolved questions that need stakeholder input. Track at feature level, not story level._
+
+| ID | Question | Owner | Status | Resolution |
+|----|----------|-------|--------|------------|
+| Q-001 | [Question] | [Name] | Open / Resolved | [Answer if resolved] |
+
+---
+
+## Related Features
+
+_Features that interact with or depend on this one._
+
+| Feature ID | Relationship |
+|------------|--------------|
+| [F-XXX] | [Depends on / Extends / Conflicts with] |
+
+---
+
+## Change Log
+
+<!-- TEAMSPEC RULE: TS-DOD-001 - Stories must be referenced here -->
+
+> ⚠️ **APPEND-ONLY**: Never delete entries. This is the audit trail.  
+> Every completed story that adds/changes behavior MUST be logged here.
+
+| Date | Story ID | Change Summary | Author |
+|------|----------|----------------|--------|
+| YYYY-MM-DD | — | Initial feature creation | [BA Name] |
+| YYYY-MM-DD | S-XXX | [Description of change] | [FA Name] |
+
+---
+
+## Story Ledger Reference
+
+> All stories that have modified this feature:
+
+See [story-ledger.md](./story-ledger.md) for the complete history.
+
+**Last Story:** S-XXX  
+**Last Update:** YYYY-MM-DD
+
+---
+
+## Implementation References
+
+_Links to code, APIs, or technical documentation. Maintained by DEV._
+
+- **Primary Service**: [Link or path]
+- **API Documentation**: [Link]
+- **Database Schema**: [Link or reference]
+
+---
+
+## Linter Rules Enforced
+
+| Rule | Description |
+|------|-------------|
+| TS-FEAT-001 | Feature file must exist before stories can reference it |
+| TS-FEAT-002 | All required sections must be present |
+| TS-FEAT-003 | Feature ID must be unique |
+| TS-DOD-001 | Change Log must be updated when stories complete |

package/teamspec-core/templates/functional-spec-template.md

@@ -0,0 +1,161 @@
+# Functional Specification: [Feature Name]
+
+<!-- 
+  ℹ️ THIS IS A TRANSITIONAL DOCUMENT
+  
+  This Functional Specification bridges Business Analysis and Feature Canon.
+  
+  LIFECYCLE:
+  1. Created during functional elaboration
+  2. Used to refine Feature Canon
+  3. RETIRED after Feature Canon stabilizes
+  
+  Once the Feature Canon (F-XXX.md) is complete and stable,
+  this document should be archived and marked as superseded.
+-->
+
+> **Template Version**: 2.0  
+> **Last Updated**: 2026-01-07
+
+---
+
+**Document Owner:** FA (Functional Analyst)  
+**Artifact Type:** Transitional (Working Document)  
+**Lifecycle:** Retired after Feature Canon stabilizes
+
+| Metadata | Details |
+| :--- | :--- |
+| **Source BA Doc** | [Link to BA Doc] |
+| **Owner** | [FA Name] |
+| **Tech Lead** | [Arch/Dev Name] |
+| **Created** | YYYY-MM-DD |
+
+---
+
+## Target Feature Canon
+
+> ⚠️ This spec elaborates behavior for the Feature Canon below.
+> The Feature Canon is the authoritative source.
+> This spec is a working document during elaboration only.
+
+| Feature ID | Feature Name | Link |
+|------------|--------------|------|
+| [F-XXX](../features/F-XXX-name.md) | [Feature Name] | |
+
+---
+
+## 1. Feature Overview
+
+> Summary for Developers - Read this first!
+
+- **Building**: [What]
+- **Key Constraints**: [Hard rules]
+- **Risks**: [Top technical risks]
+
+> **Reference the Feature Canon** for full behavioral context before developing.
+
+---
+
+## 2. Functional Requirements
+
+### FR-01: [Requirement Name]
+
+- **Description**: Detailed behavior.
+- **Alignment**: Maps to Feature Canon section [F-XXX: Current Behavior > ...]
+- **Validation**:
+  - [Rule 1]
+  - [Rule 2]
+- **Error States**:
+  - If [Condition], show "Error Message".
+
+### FR-02: [Requirement Name]
+
+...
+
+---
+
+## 3. User Interface (UI/UX)
+
+- **Screen 1**: [Link to Figma] - Description of logic.
+- **Screen 2**: ...
+
+---
+
+## 4. Role-Based Access
+
+| Role | View | Edit | Delete |
+| :--- | :---: | :---: | :---: |
+| Admin | ✓ | ✓ | ✓ |
+| Viewer | ✓ | — | — |
+
+> Note: These roles and permissions will be documented in the Feature Canon.
+
+---
+
+## 5. Data Interactions
+
+- **Inputs**: [Form fields]
+- **Outputs**: [Display fields]
+
+---
+
+## 6. Story Slicing Strategy
+
+> Suggested breakdown of work. Stories will be created by FA referencing this spec.
+
+| Story | Scope | Feature Impact |
+|-------|-------|----------------|
+| Story 1 | [Core Slice] | Adds Behavior |
+| Story 2 | [Edge Case] | Adds Behavior |
+| Story 3 | [Refinement] | Changes Behavior |
+
+---
+
+## Authoritative Source Rule
+
+> ⚠️ This Functional Specification is a **transitional planning document**.
+> 
+> Once stories are implemented:
+> - **Feature Canon** is the authoritative reference
+> - Stories become historical records
+> - This spec may become stale
+> 
+> **If you discover a discrepancy** between this spec and the Feature Canon:
+> - Check Feature file's Change Log to understand what changed
+> - If behavior is wrong, file a bug
+> - If Feature Canon is stale, run `ts:fa sync`
+
+---
+
+## Document Retirement
+
+> This document should be retired when:
+
+- [ ] Feature Canon (F-XXX) is complete
+- [ ] All business rules transferred to Feature Canon
+- [ ] All edge cases documented in Feature Canon
+- [ ] Stakeholder validation complete
+- [ ] Feature Canon is source of truth
+
+**Retirement Status:** [ ] Active / [ ] Superseded  
+**Superseded By:** [F-XXX](../features/F-XXX-name.md)  
+**Retirement Date:** ________________
+
+---
+
+## Transition Checklist
+
+Before retiring this document:
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Purpose section in Feature Canon | [ ] | |
+| Business Value in Feature Canon | [ ] | |
+| Scope (In/Out) in Feature Canon | [ ] | |
+| Current Behavior in Feature Canon | [ ] | |
+| Business Rules (BR-XXX) in Feature Canon | [ ] | |
+| Edge Cases in Feature Canon | [ ] | |
+| Roles & Permissions in Feature Canon | [ ] | |
+
+**Transition Verified By:** ________________  
+**Date:** ________________