@sniper.ai/core 1.0.0 → 2.0.0

package/framework/templates/coverage-report.md

@@ -0,0 +1,67 @@
+# Coverage Report: {title}
+
+> **Audit ID:** TST-{NNN}
+> **Status:** Analyzing
+> **Date:** {date}
+> **Author:** Coverage Analyst
+
+## Coverage Summary
+<!-- sniper:managed:coverage-summary:start -->
+
+| Metric | Coverage | Target |
+|--------|----------|--------|
+| Lines | | |
+| Branches | | |
+| Functions | | |
+| Statements | | |
+
+<!-- sniper:managed:coverage-summary:end -->
+
+## Critical Gaps
+<!-- sniper:managed:critical-gaps:start -->
+<!-- Uncovered code ranked by risk — public APIs first, then business logic, then utilities -->
+
+### Gap 1: {description}
+- **File:** `path/to/file.ts:42-67`
+- **Risk:** Critical / High / Medium / Low
+- **What's uncovered:** {description of the uncovered code path}
+- **Why it matters:** {production impact if this code fails}
+- **Suggested test approach:** {how to test it}
+- **Effort:** S / M / L
+
+<!-- sniper:managed:critical-gaps:end -->
+
+## Integration Boundaries
+<!-- sniper:managed:integration-boundaries:start -->
+<!-- Places where modules/services interact that lack integration tests -->
+
+| Boundary | Components | Integration Tests? | Risk |
+|----------|------------|-------------------|------|
+| | A ↔ B | None / Partial / Good | |
+
+<!-- sniper:managed:integration-boundaries:end -->
+
+## Test Pattern Analysis
+<!-- sniper:managed:test-patterns:start -->
+<!-- Assessment of testing consistency across the codebase -->
+
+| Aspect | Current State | Recommendation |
+|--------|--------------|----------------|
+| Assertion style | | |
+| Mock patterns | | |
+| Test structure | | |
+| Naming conventions | | |
+| Setup/teardown | | |
+
+<!-- sniper:managed:test-patterns:end -->
+
+## Prioritized Recommendations
+<!-- sniper:managed:recommendations:start -->
+<!-- Ordered list of what to test next, with effort estimates -->
+
+| Priority | Recommendation | Effort | Impact |
+|----------|---------------|--------|--------|
+| 1 | | S/M/L | |
+| 2 | | S/M/L | |
+
+<!-- sniper:managed:recommendations:end -->

package/framework/templates/epic.md

@@ -1,11 +1,16 @@
 # Epic {number}: {title}
 
+> **Version:** 1
 > **Status:** Draft
+> **Last Updated:** {date}
 > **Priority:** P{0|1|2}
 > **Estimated Points:** {total}
 > **Dependencies:** {epic dependencies or "None"}
+> **Change Log:**
+> - v1 ({date}): Initial version
 
 ## Scope
+<!-- sniper:managed:scope:start -->
 <!-- What this epic covers and what it explicitly does NOT cover -->
 
 ### In Scope
@@ -13,21 +18,30 @@
 
 ### Out of Scope
 -
+<!-- sniper:managed:scope:end -->
 
 ## Architecture Context
+<!-- sniper:managed:architecture-context:start -->
 <!-- EMBED relevant sections from docs/architecture.md — don't just reference -->
+<!-- sniper:managed:architecture-context:end -->
 
 ## Stories
+<!-- sniper:managed:stories:start -->
 | # | Story | Complexity | Dependencies | Owner |
 |---|-------|-----------|-------------|-------|
 | {epic}.1 | | S/M/L/XL | | backend/frontend/infra |
 | {epic}.2 | | | | |
+<!-- sniper:managed:stories:end -->
 
 ## Acceptance Criteria
+<!-- sniper:managed:acceptance-criteria:start -->
 <!-- Epic-level acceptance criteria — what must be true when ALL stories are done -->
 1.
 2.
 3.
+<!-- sniper:managed:acceptance-criteria:end -->
 
 ## Technical Notes
+<!-- sniper:managed:technical-notes:start -->
 <!-- Any technical considerations specific to this epic -->
+<!-- sniper:managed:technical-notes:end -->

package/framework/templates/feature-brief.md

@@ -0,0 +1,54 @@
+# Feature Brief: {title}
+
+> **Feature ID:** SNPR-{XXXX}
+> **Version:** 1
+> **Status:** Draft
+> **Date:** {date}
+> **Author:** Feature Scoping Agent
+> **Change Log:**
+> - v1 ({date}): Initial version
+
+## Feature Description
+<!-- sniper:managed:feature-description:start -->
+<!-- What this feature does, in user-facing terms -->
+<!-- sniper:managed:feature-description:end -->
+
+## Motivation
+<!-- sniper:managed:motivation:start -->
+<!-- Why this feature is needed. What user problem does it solve? -->
+<!-- sniper:managed:motivation:end -->
+
+## Affected Areas
+<!-- sniper:managed:affected-areas:start -->
+
+### Components Affected
+| Component | Impact | Notes |
+|-----------|--------|-------|
+| | Low / Medium / High | |
+
+### Files Likely Modified
+- `path/to/file.ts` — reason
+
+<!-- sniper:managed:affected-areas:end -->
+
+## Scope
+
+### In Scope
+<!-- sniper:managed:in-scope:start -->
+-
+<!-- sniper:managed:in-scope:end -->
+
+### Out of Scope
+<!-- sniper:managed:out-of-scope:start -->
+-
+<!-- sniper:managed:out-of-scope:end -->
+
+## Risks & Open Questions
+<!-- sniper:managed:risks:start -->
+1.
+<!-- sniper:managed:risks:end -->
+
+## Dependencies
+<!-- sniper:managed:dependencies:start -->
+<!-- External services, libraries, or other features needed -->
+<!-- sniper:managed:dependencies:end -->

package/framework/templates/feature-spec.md

@@ -0,0 +1,53 @@
+# Feature Spec: {title}
+
+> **Feature ID:** SNPR-{XXXX}
+> **Version:** 1
+> **Status:** Draft
+> **Date:** {date}
+> **Author:** Feature Planning Team — PM
+> **Source:** `docs/features/SNPR-{XXXX}/brief.md`
+> **Change Log:**
+> - v1 ({date}): Initial version
+
+## Requirements
+
+### Functional Requirements
+<!-- sniper:managed:functional-requirements:start -->
+| ID | Requirement | Priority | Acceptance Criteria |
+|----|------------|----------|-------------------|
+| FR-001 | | P0 | |
+<!-- sniper:managed:functional-requirements:end -->
+
+### Non-Functional Requirements
+<!-- sniper:managed:nonfunctional-requirements:start -->
+| Category | Requirement | Target |
+|----------|------------|--------|
+| | | |
+<!-- sniper:managed:nonfunctional-requirements:end -->
+
+## User Stories
+<!-- sniper:managed:user-stories:start -->
+| ID | As a... | I want to... | So that... |
+|----|---------|-------------|-----------|
+| US-001 | | | |
+<!-- sniper:managed:user-stories:end -->
+
+## API Changes
+<!-- sniper:managed:api-changes:start -->
+<!-- New endpoints, modified endpoints, deprecated endpoints -->
+<!-- sniper:managed:api-changes:end -->
+
+## Data Model Changes
+<!-- sniper:managed:data-model-changes:start -->
+<!-- New tables/collections, modified schemas, migrations needed -->
+<!-- sniper:managed:data-model-changes:end -->
+
+## UI Changes
+<!-- sniper:managed:ui-changes:start -->
+<!-- New screens, modified screens, new components -->
+<!-- sniper:managed:ui-changes:end -->
+
+## Rollout Strategy
+<!-- sniper:managed:rollout:start -->
+<!-- Feature flag? Gradual rollout? Migration needed? -->
+<!-- sniper:managed:rollout:end -->

package/framework/templates/flaky-report.md

@@ -0,0 +1,64 @@
+# Flaky Test Report: {title}
+
+> **Audit ID:** TST-{NNN}
+> **Status:** Analyzing
+> **Date:** {date}
+> **Author:** Flake Hunter
+
+## Flake Summary
+<!-- sniper:managed:flake-summary:start -->
+
+| Root Cause Category | Count |
+|-------------------|-------|
+| Timing | |
+| Shared state | |
+| Network dependency | |
+| Race condition | |
+| Non-deterministic data | |
+| Environment coupling | |
+| **Total** | |
+
+<!-- sniper:managed:flake-summary:end -->
+
+## Flaky Test Inventory
+<!-- sniper:managed:flaky-tests:start -->
+
+### {Test Name}
+- **File:** `path/to/test.ts:42`
+- **Root cause:** Timing / Shared state / Network / Race condition / Non-deterministic data / Environment
+- **Evidence:** {how the flakiness was detected or reproduced}
+- **Suggested fix:** {specific remediation approach}
+- **Effort:** S / M / L
+
+<!-- sniper:managed:flaky-tests:end -->
+
+## Systemic Issues
+<!-- sniper:managed:systemic-issues:start -->
+<!-- Patterns that cause multiple flaky tests -->
+
+### {Issue Title}
+- **Affected tests:** {count} tests
+- **Root cause:** {description of the systemic pattern}
+- **Examples:** {list of affected test files}
+- **Fix approach:** {how to fix the systemic issue}
+
+<!-- sniper:managed:systemic-issues:end -->
+
+## Quick Wins
+<!-- sniper:managed:quick-wins:start -->
+<!-- Flaky tests that can be fixed with minimal effort -->
+
+| Test | Fix | Effort |
+|------|-----|--------|
+| | | S |
+
+<!-- sniper:managed:quick-wins:end -->
+
+## Prevention Recommendations
+<!-- sniper:managed:prevention:start -->
+<!-- Patterns and guardrails to prevent future flaky tests -->
+
+1. {Recommendation}
+2. {Recommendation}
+
+<!-- sniper:managed:prevention:end -->

package/framework/templates/investigation.md

@@ -0,0 +1,49 @@
+# Investigation: {title}
+
+> **Bug ID:** BUG-{NNN}
+> **Status:** Investigating
+> **Date:** {date}
+> **Based on:** `docs/bugs/BUG-{NNN}/report.md`
+
+## Log Findings
+<!-- sniper:managed:log-findings:start -->
+<!-- Findings from the Log Analyst -->
+
+### Error Patterns
+<!-- What errors were found, their frequency, and timing -->
+
+### Correlations
+<!-- Patterns in who/what/when is affected -->
+
+### Evidence
+<!-- Specific error messages, stack traces, and their locations -->
+
+<!-- sniper:managed:log-findings:end -->
+
+## Code Findings
+<!-- sniper:managed:code-findings:start -->
+<!-- Findings from the Code Investigator -->
+
+### Execution Path
+<!-- The code path from entry point to failure: file:line → file:line → FAILURE -->
+
+### Root Cause Identification
+<!-- The specific code, condition, or data state that causes the failure -->
+
+### Recent Changes
+<!-- Relevant git history for affected files -->
+
+### Related Fragile Code
+<!-- Other code nearby with similar vulnerability patterns -->
+
+<!-- sniper:managed:code-findings:end -->
+
+## Root Cause
+<!-- sniper:managed:root-cause:start -->
+<!-- Combined analysis: the definitive root cause explanation -->
+<!-- sniper:managed:root-cause:end -->
+
+## Recommended Fix
+<!-- sniper:managed:recommended-fix:start -->
+<!-- What should be changed to fix the issue -->
+<!-- sniper:managed:recommended-fix:end -->

package/framework/templates/memory-anti-pattern.yaml

@@ -0,0 +1,16 @@
+# Anti-Pattern Entry Template
+# Add to: .sniper/memory/anti-patterns.yaml
+
+# - id: ap-XXX                     # Auto-assigned sequential ID
+#   description: ""                 # What the anti-pattern is
+#   why_bad: ""                     # Why it's problematic
+#   fix_pattern: ""                 # What to do instead
+#   source:
+#     type: review_gate | retro | manual | imported
+#     ref: ""                       # Source reference
+#     story: ""                     # Story where it was found (optional)
+#     date: ""                      # ISO 8601 date
+#   detection_hint: ""              # Grep/search pattern to detect this
+#   applies_to: []                  # Agent roles
+#   severity: high | medium | low
+#   status: confirmed | candidate

package/framework/templates/memory-convention.yaml

@@ -0,0 +1,17 @@
+# Convention Entry Template
+# Add to: .sniper/memory/conventions.yaml
+
+# - id: conv-XXX                    # Auto-assigned sequential ID
+#   rule: ""                        # Clear, imperative statement of the convention
+#   rationale: ""                   # Why this convention exists
+#   source:
+#     type: review_gate | retro | manual | imported
+#     ref: ""                       # Source reference (sprint name, review ID, etc.)
+#     date: ""                      # ISO 8601 date
+#   applies_to: []                  # Agent roles: backend-engineer, frontend-engineer, architect, etc.
+#   enforcement: review_gate | spawn_prompt | both
+#   scope: project | workspace     # project = this repo only, workspace = all repos
+#   status: confirmed | candidate  # candidate = needs one more occurrence to confirm
+#   examples:
+#     positive: ""                  # Example of correct usage
+#     negative: ""                  # Example of incorrect usage

package/framework/templates/memory-decision.yaml

@@ -0,0 +1,16 @@
+# Decision Entry Template
+# Add to: .sniper/memory/decisions.yaml
+
+# - id: dec-XXX                    # Auto-assigned sequential ID
+#   title: ""                       # Short title for the decision
+#   context: ""                     # What problem or question prompted this decision
+#   decision: ""                    # What was decided
+#   alternatives_considered:        # What other options were evaluated
+#     - ""
+#   source:
+#     type: review_gate | retro | manual | imported
+#     ref: ""                       # Source reference
+#     date: ""                      # ISO 8601 date
+#   applies_to: []                  # Agent roles
+#   status: active | superseded | deprecated
+#   superseded_by: null             # ID of the decision that replaced this one

package/framework/templates/migration-plan.md

@@ -0,0 +1,47 @@
+# Migration Plan: {title}
+
+> **Refactor ID:** REF-{NNN}
+> **Status:** Planning
+> **Date:** {date}
+> **Author:** Migration Architect
+> **Based on:** `docs/refactors/REF-{NNN}/scope.md`
+
+## Migration Strategy
+<!-- sniper:managed:strategy:start -->
+<!-- Big-bang vs incremental vs strangler fig, with justification -->
+<!-- sniper:managed:strategy:end -->
+
+## Step-by-Step Approach
+<!-- sniper:managed:steps:start -->
+
+### Step 1: {description}
+- **What changes:**
+- **Why this order:**
+- **Verification:**
+
+### Step 2: {description}
+- **What changes:**
+- **Why this order:**
+- **Verification:**
+
+<!-- sniper:managed:steps:end -->
+
+## Coexistence Plan
+<!-- sniper:managed:coexistence:start -->
+<!-- How old and new patterns coexist during migration -->
+<!-- sniper:managed:coexistence:end -->
+
+## Compatibility Layer
+<!-- sniper:managed:compatibility:start -->
+<!-- Adapter patterns, deprecation warnings, backward-compatible wrappers -->
+<!-- sniper:managed:compatibility:end -->
+
+## Verification Strategy
+<!-- sniper:managed:verification:start -->
+<!-- How to verify each step worked: tests, canary, metrics -->
+<!-- sniper:managed:verification:end -->
+
+## Rollback Plan
+<!-- sniper:managed:rollback:start -->
+<!-- How to undo each step if something goes wrong -->
+<!-- sniper:managed:rollback:end -->

package/framework/templates/optimization-plan.md

@@ -0,0 +1,59 @@
+# Optimization Plan: {title}
+
+> **Audit ID:** PERF-{NNN}
+> **Status:** Planning
+> **Date:** {date}
+> **Author:** Lead
+
+## Priority Matrix
+<!-- sniper:managed:priority-matrix:start -->
+<!-- Bottlenecks ranked by impact / effort ratio -->
+
+| Rank | Bottleneck | Impact | Effort | Ratio | Category |
+|------|-----------|--------|--------|-------|----------|
+| 1 | | High/Med/Low | S/M/L | | Quick win / Standard / Major |
+
+<!-- sniper:managed:priority-matrix:end -->
+
+## Optimization Recommendations
+<!-- sniper:managed:recommendations:start -->
+
+### Optimization 1: {title}
+- **Bottleneck:** {reference to bottleneck from profile report}
+- **What to change:** {specific change description}
+- **Expected improvement:** {e.g., "reduces O(n) DB calls to O(1)"}
+- **Implementation approach:** {how to implement}
+- **Risks and trade-offs:** {e.g., "caching adds complexity, requires cache invalidation strategy"}
+- **Benchmark:** {how to verify the improvement}
+
+<!-- sniper:managed:recommendations:end -->
+
+## Benchmark Requirements
+<!-- sniper:managed:benchmarks:start -->
+<!-- What benchmarks should be written to verify each optimization -->
+
+| Optimization | Benchmark Description | Metrics to Capture |
+|-------------|----------------------|-------------------|
+| | | Latency / Throughput / Memory / DB calls |
+
+<!-- sniper:managed:benchmarks:end -->
+
+## Quick Wins
+<!-- sniper:managed:quick-wins:start -->
+<!-- Low-effort, high-impact optimizations -->
+
+| Optimization | Effort | Expected Impact |
+|-------------|--------|-----------------|
+| | S | |
+
+<!-- sniper:managed:quick-wins:end -->
+
+## Monitoring Recommendations
+<!-- sniper:managed:monitoring:start -->
+<!-- Metrics to track for regression prevention -->
+
+| Metric | Current Baseline | Target | Alert Threshold |
+|--------|-----------------|--------|----------------|
+| | | | |
+
+<!-- sniper:managed:monitoring:end -->

package/framework/templates/performance-profile.md

@@ -0,0 +1,64 @@
+# Performance Profile: {title}
+
+> **Audit ID:** PERF-{NNN}
+> **Status:** Analyzing
+> **Date:** {date}
+> **Author:** Performance Profiler
+
+## Performance Context
+<!-- sniper:managed:context:start -->
+<!-- What was investigated and why -->
+<!-- sniper:managed:context:end -->
+
+## Critical Path Analysis
+<!-- sniper:managed:critical-paths:start -->
+<!-- The most performance-sensitive paths in the application -->
+
+### Path: {name}
+- **Type:** Request handling / Data pipeline / Background job
+- **Flow:** {entry} → {step 1} → {step 2} → {response}
+- **I/O Operations:** {count} database calls, {count} external service calls
+- **Estimated Latency Contribution:** {description}
+
+<!-- sniper:managed:critical-paths:end -->
+
+## Bottleneck Inventory
+<!-- sniper:managed:bottlenecks:start -->
+
+### Bottleneck 1: {title}
+- **Location:** `path/to/file.ts:42`
+- **Category:** N+1 query / Missing index / Synchronous I/O / Unbounded loop / Missing cache / Excessive serialization / Memory leak pattern / Large payload
+- **Evidence:** {the code pattern that causes the bottleneck}
+- **Impact:** Critical / High / Medium / Low
+- **Complexity:** S / M / L
+- **Details:** {explanation of why this is a bottleneck}
+
+<!-- sniper:managed:bottlenecks:end -->
+
+## Resource Usage Patterns
+<!-- sniper:managed:resource-patterns:start -->
+
+| Resource | Observation | Concern Level |
+|----------|------------|---------------|
+| Memory allocation | | Low / Medium / High |
+| Connection pools | | Low / Medium / High |
+| Compute operations | | Low / Medium / High |
+
+<!-- sniper:managed:resource-patterns:end -->
+
+## Existing Optimizations
+<!-- sniper:managed:existing-optimizations:start -->
+<!-- Caching, indexing, and optimization patterns already in place -->
+
+- {Optimization — e.g., "Redis cache on product catalog with 5-minute TTL"}
+
+<!-- sniper:managed:existing-optimizations:end -->
+
+## Benchmark Coverage
+<!-- sniper:managed:benchmark-coverage:start -->
+
+| Critical Path | Has Benchmark? | Benchmark File |
+|--------------|---------------|----------------|
+| | Yes / No | |
+
+<!-- sniper:managed:benchmark-coverage:end -->

package/framework/templates/postmortem.md

@@ -0,0 +1,69 @@
+# Post-Mortem: {title}
+
+> **Bug ID:** BUG-{NNN}
+> **Severity:** {critical/high/medium/low}
+> **Status:** Complete
+> **Date:** {date}
+> **Resolution Date:** {date}
+
+## Root Cause
+<!-- sniper:managed:root-cause:start -->
+<!-- What specifically was wrong — the definitive explanation -->
+<!-- sniper:managed:root-cause:end -->
+
+## Fix Summary
+<!-- sniper:managed:fix-summary:start -->
+<!-- What was changed and why -->
+
+### Files Changed
+| File | Change |
+|------|--------|
+| | |
+
+### Code Changes
+<!-- Brief description of the fix approach -->
+
+<!-- sniper:managed:fix-summary:end -->
+
+## Impact Assessment
+<!-- sniper:managed:impact:start -->
+<!-- Who was affected, for how long, what was the business impact -->
+<!-- sniper:managed:impact:end -->
+
+## Prevention
+<!-- sniper:managed:prevention:start -->
+<!-- What should change to prevent similar bugs in the future -->
+
+### Process Changes
+-
+
+### Code Changes
+-
+
+### Monitoring/Alerting
+-
+
+<!-- sniper:managed:prevention:end -->
+
+## Regression Tests
+<!-- sniper:managed:regression-tests:start -->
+<!-- What tests were added to prevent recurrence -->
+
+| Test | File | Verifies |
+|------|------|----------|
+| | | |
+
+<!-- sniper:managed:regression-tests:end -->
+
+## Timeline
+<!-- sniper:managed:timeline:start -->
+
+| Time | Event |
+|------|-------|
+| {timestamp} | Bug reported |
+| {timestamp} | Triage complete |
+| {timestamp} | Investigation complete |
+| {timestamp} | Fix applied |
+| {timestamp} | Regression tests passing |
+
+<!-- sniper:managed:timeline:end -->

package/framework/templates/pr-review.md

@@ -0,0 +1,50 @@
+# PR Review: #{pr_number} — {pr_title}
+
+> **Review ID:** PR-{NNN}
+> **Date:** {date}
+> **Reviewers:** Code Reviewer, Security Reviewer, Test Reviewer
+> **Recommendation:** {approve / request-changes / comment}
+
+## Summary
+<!-- sniper:managed:summary:start -->
+<!-- Overall assessment of the PR -->
+<!-- sniper:managed:summary:end -->
+
+## Code Quality
+<!-- sniper:managed:code-quality:start -->
+
+| Severity | File:Line | Finding | Suggested Fix |
+|----------|-----------|---------|---------------|
+| critical / warning / suggestion | | | |
+
+<!-- sniper:managed:code-quality:end -->
+
+## Security
+<!-- sniper:managed:security:start -->
+
+| Severity | File:Line | Finding | Suggested Fix |
+|----------|-----------|---------|---------------|
+| critical / warning / suggestion | | | |
+
+<!-- sniper:managed:security:end -->
+
+## Test Coverage
+<!-- sniper:managed:test-coverage:start -->
+
+| Severity | Finding | Suggested Fix |
+|----------|---------|---------------|
+| critical / warning / suggestion | | |
+
+### Missing Tests
+-
+
+### Edge Cases Not Covered
+-
+
+<!-- sniper:managed:test-coverage:end -->
+
+## Recommendation
+<!-- sniper:managed:recommendation:start -->
+<!-- Final recommendation: approve, request changes, or comment -->
+<!-- List of items that must be addressed before merge (if any) -->
+<!-- sniper:managed:recommendation:end -->