@fractary/core 0.7.24 → 0.7.25

package/templates/docs/spec-bug/standards.md

@@ -0,0 +1,46 @@
+# Bug Fix Specification Standards
+
+## Required Conventions
+
+### 1. Bug Description
+- ALWAYS describe the bug clearly and its user-facing impact
+- Include severity/priority context if known
+- Reference the original bug report or issue number
+
+### 2. Steps to Reproduce
+- ALWAYS provide numbered steps that reliably reproduce the bug
+- ALWAYS include "Expected" and "Actual" behavior
+- Include environment details if relevant (OS, browser, version)
+
+### 3. Proposed Solution
+- ALWAYS describe the fix approach before implementing
+- Explain why this approach was chosen over alternatives
+- Identify any trade-offs or limitations of the fix
+
+### 4. Affected Areas
+- ALWAYS list all components, files, or systems affected by the bug
+- Include both directly affected and potentially impacted areas
+- This helps identify regression testing scope
+
+### 5. Testing
+- ALWAYS include regression tests that verify the fix
+- ALWAYS include edge case tests for related scenarios
+- Tests should prevent the same bug from recurring
+
+## Optional Section Guidelines
+
+### Root Cause Analysis
+- Include when the root cause is non-obvious
+- Document the investigation process for future reference
+- Identify systemic issues that may need broader fixes
+
+### Regression Risk
+- Include for fixes that touch critical code paths
+- Document which existing functionality might be affected
+- Specify additional testing needed beyond standard regression
+
+## Best Practices
+
+- Start with reproduction before proposing a fix
+- Keep the spec focused on the specific bug — broader improvements belong in a separate spec
+- Update root cause analysis as understanding evolves during investigation

package/templates/docs/spec-bug/template.md

@@ -0,0 +1,66 @@
+---
+title: "{{title}}"
+fractary_doc_type: spec-bug
+status: {{status}}
+date: {{date}}
+{{#work_id}}
+work_id: "{{work_id}}"
+{{/work_id}}
+{{#work_type}}
+work_type: {{work_type}}
+{{/work_type}}
+source: {{source}}
+validation_status: not_validated
+tags: []
+---
+
+# {{title}}
+
+## Bug Description
+
+{{description}}
+
+## Steps to Reproduce
+
+1. {{#steps}}{{.}}
+{{/steps}}
+
+**Expected:** {{expected}}
+
+**Actual:** {{actual}}
+
+{{#root_cause}}
+## Root Cause Analysis
+
+{{root_cause}}
+{{/root_cause}}
+
+## Proposed Solution
+
+{{solution}}
+
+## Affected Areas
+
+{{#affected_areas}}
+- {{.}}
+{{/affected_areas}}
+
+## Testing
+
+### Regression Tests
+
+{{#regression_tests}}
+- [ ] {{.}}
+{{/regression_tests}}
+
+### Edge Case Tests
+
+{{#edge_case_tests}}
+- [ ] {{.}}
+{{/edge_case_tests}}
+
+{{#regression_risk}}
+## Regression Risk
+
+{{regression_risk}}
+{{/regression_risk}}

package/templates/docs/spec-bug/type.yaml

@@ -0,0 +1,96 @@
+id: spec-bug
+display_name: Bug Fix Specification
+description: Specification for bug investigation and fix
+
+output_path: specs
+
+file_naming:
+  pattern: "WORK-{work_id}-{slug}.md"
+  auto_number: false
+  slug_source: title
+  slug_max_length: 50
+
+frontmatter:
+  required_fields:
+    - title
+    - fractary_doc_type
+    - status
+    - date
+  optional_fields:
+    - work_id
+    - work_type
+    - source
+    - validation_status
+    - tags
+    - author
+    - related
+    - changelog
+  defaults:
+    fractary_doc_type: spec-bug
+    status: draft
+    source: conversation
+    validation_status: not_validated
+
+structure:
+  required_sections:
+    - Bug Description
+    - Steps to Reproduce
+    - Proposed Solution
+    - Affected Areas
+    - Testing
+  optional_sections:
+    - Root Cause Analysis
+    - Regression Risk
+    - References
+  section_order:
+    - Bug Description
+    - Steps to Reproduce
+    - Root Cause Analysis
+    - Proposed Solution
+    - Affected Areas
+    - Testing
+    - Regression Risk
+    - References
+
+status:
+  allowed_values:
+    - draft
+    - review
+    - approved
+    - in-progress
+    - completed
+    - archived
+  default: draft
+
+index_config:
+  index_file: specs/README.md
+  sort_by: date
+  sort_order: desc
+  entry_template: "- [**{{work_id}}**: {{title}}]({{relative_path}}) — {{status}}"
+
+archive:
+  enabled: true
+  source: archive
+  trigger: on_status_change
+  trigger_statuses:
+    - archived
+  verify_checksum: true
+  delete_original: true
+
+work_linking:
+  enabled: true
+  comment_on_create: true
+  comment_on_archive: true
+  require_closed_for_archive: true
+
+refinement:
+  enabled: true
+  post_questions_to_work_item: true
+  maintain_changelog: true
+
+fulfillment:
+  enabled: true
+  check_acceptance_criteria: true
+  check_files_modified: true
+  check_tests_added: true
+  check_docs_updated: false

package/templates/docs/spec-feature/standards.md

@@ -0,0 +1,53 @@
+# Feature Specification Standards
+
+## Required Conventions
+
+### 1. Overview
+- ALWAYS provide a clear, concise summary of the feature and its value
+- ALWAYS explain why this feature is needed (business context)
+- NEVER leave the overview as a placeholder
+
+### 2. User Stories
+- ALWAYS write user stories in "As a [role], I want [goal] so that [benefit]" format
+- ALWAYS include at least one user story
+- Each story should represent a distinct use case
+
+### 3. Requirements
+- ALWAYS separate functional and non-functional requirements
+- ALWAYS write requirements as checkable items (- [ ] format)
+- Requirements should be specific, measurable, and testable
+- NEVER use vague language ("should be fast", "must be good")
+
+### 4. Acceptance Criteria
+- ALWAYS write acceptance criteria as verifiable checkboxes
+- Each criterion should be independently testable
+- Include both happy path and error scenarios
+- NEVER duplicate requirements as acceptance criteria verbatim
+
+### 5. Testing Strategy
+- ALWAYS specify test types (unit, integration, e2e)
+- ALWAYS include specific test scenarios, not just categories
+- Testing should cover all acceptance criteria
+
+## Optional Section Guidelines
+
+### Technical Design
+- Include when the implementation approach is non-obvious
+- Document key architectural decisions and trade-offs
+- Reference existing patterns in the codebase
+
+### API Changes
+- Document all new or modified endpoints
+- Include request/response schemas
+- Document error codes and edge cases
+
+### Rollout Plan
+- Include for features requiring phased deployment
+- Document feature flags, migration steps, or rollback procedures
+
+## Best Practices
+
+- Keep specs focused on WHAT and WHY, not HOW (implementation details belong in code)
+- Link related specs via the `related` frontmatter field
+- Update the spec as understanding evolves (use the refinement changelog)
+- Mark acceptance criteria as complete during implementation

package/templates/docs/spec-feature/template.md

@@ -0,0 +1,105 @@
+---
+title: "{{title}}"
+fractary_doc_type: spec-feature
+status: {{status}}
+date: {{date}}
+{{#work_id}}
+work_id: "{{work_id}}"
+{{/work_id}}
+{{#work_type}}
+work_type: {{work_type}}
+{{/work_type}}
+source: {{source}}
+validation_status: not_validated
+tags: []
+---
+
+# {{title}}
+
+## Overview
+
+{{overview}}
+
+## User Stories
+
+{{#user_stories}}
+- As a {{role}}, I want {{goal}} so that {{benefit}}
+{{/user_stories}}
+
+## Requirements
+
+### Functional
+
+{{#functional_requirements}}
+- [ ] {{.}}
+{{/functional_requirements}}
+
+### Non-Functional
+
+{{#nonfunctional_requirements}}
+- [ ] {{.}}
+{{/nonfunctional_requirements}}
+
+{{#technical_design}}
+## Technical Design
+
+{{technical_design}}
+{{/technical_design}}
+
+{{#api_changes}}
+## API Changes
+
+{{api_changes}}
+{{/api_changes}}
+
+{{#data_model}}
+## Data Model
+
+{{data_model}}
+{{/data_model}}
+
+## Acceptance Criteria
+
+{{#acceptance_criteria}}
+- [ ] {{.}}
+{{/acceptance_criteria}}
+
+## Testing Strategy
+
+### Unit Tests
+
+{{#unit_tests}}
+- [ ] {{.}}
+{{/unit_tests}}
+
+### Integration Tests
+
+{{#integration_tests}}
+- [ ] {{.}}
+{{/integration_tests}}
+
+{{#security_considerations}}
+## Security Considerations
+
+{{security_considerations}}
+{{/security_considerations}}
+
+{{#performance_considerations}}
+## Performance Considerations
+
+{{performance_considerations}}
+{{/performance_considerations}}
+
+{{#rollout_plan}}
+## Rollout Plan
+
+{{rollout_plan}}
+{{/rollout_plan}}
+
+{{#open_questions}}
+## Open Questions
+
+{{#open_questions}}
+- [ ] {{.}}
+{{/open_questions}}
+{{/open_questions}}

package/templates/docs/spec-feature/type.yaml

@@ -0,0 +1,106 @@
+id: spec-feature
+display_name: Feature Specification
+description: Comprehensive specification for new feature development
+
+output_path: specs
+
+file_naming:
+  pattern: "WORK-{work_id}-{slug}.md"
+  auto_number: false
+  slug_source: title
+  slug_max_length: 50
+
+frontmatter:
+  required_fields:
+    - title
+    - fractary_doc_type
+    - status
+    - date
+  optional_fields:
+    - work_id
+    - work_type
+    - source
+    - validation_status
+    - tags
+    - author
+    - related
+    - changelog
+  defaults:
+    fractary_doc_type: spec-feature
+    status: draft
+    source: conversation
+    validation_status: not_validated
+
+structure:
+  required_sections:
+    - Overview
+    - User Stories
+    - Requirements
+    - Acceptance Criteria
+    - Testing Strategy
+  optional_sections:
+    - Technical Design
+    - API Changes
+    - Data Model
+    - Rollout Plan
+    - Security Considerations
+    - Performance Considerations
+    - Open Questions
+    - References
+  section_order:
+    - Overview
+    - User Stories
+    - Requirements
+    - Technical Design
+    - API Changes
+    - Data Model
+    - Acceptance Criteria
+    - Testing Strategy
+    - Security Considerations
+    - Performance Considerations
+    - Rollout Plan
+    - Open Questions
+    - References
+
+status:
+  allowed_values:
+    - draft
+    - review
+    - approved
+    - in-progress
+    - completed
+    - archived
+  default: draft
+
+index_config:
+  index_file: specs/README.md
+  sort_by: date
+  sort_order: desc
+  entry_template: "- [**{{work_id}}**: {{title}}]({{relative_path}}) — {{status}}"
+
+archive:
+  enabled: true
+  source: archive
+  trigger: on_status_change
+  trigger_statuses:
+    - archived
+  verify_checksum: true
+  delete_original: true
+
+work_linking:
+  enabled: true
+  comment_on_create: true
+  comment_on_archive: true
+  require_closed_for_archive: true
+
+refinement:
+  enabled: true
+  post_questions_to_work_item: true
+  maintain_changelog: true
+
+fulfillment:
+  enabled: true
+  check_acceptance_criteria: true
+  check_files_modified: true
+  check_tests_added: true
+  check_docs_updated: true

package/templates/docs/spec-infrastructure/standards.md

@@ -0,0 +1,58 @@
+# Infrastructure Specification Standards
+
+## Required Conventions
+
+### 1. Objective
+- ALWAYS state the infrastructure change clearly and its motivation
+- Include the expected outcome and success metrics
+- Reference the triggering event (scaling need, incident, new service, etc.)
+
+### 2. Current State
+- ALWAYS document the existing infrastructure configuration
+- Include relevant diagrams, resource counts, or architecture references
+- Specify the baseline metrics (current capacity, cost, performance)
+
+### 3. Proposed Changes
+- ALWAYS write changes as checkable items (- [ ] format)
+- Specify exact resources being added, modified, or removed
+- Include configuration values (instance types, region, sizing, etc.)
+
+### 4. Security Considerations
+- ALWAYS document security implications of the change
+- Address network access, IAM permissions, encryption, and secrets management
+- Include any compliance requirements (SOC2, HIPAA, GDPR, etc.)
+
+### 5. Rollback Plan
+- ALWAYS document step-by-step rollback procedure
+- Specify the rollback trigger criteria (what failure conditions warrant rollback)
+- Include estimated rollback time
+- NEVER deploy infrastructure changes without a rollback plan
+
+### 6. Verification
+- ALWAYS include verification steps as checkable items
+- Include health checks, smoke tests, and monitoring confirmation
+- Specify who needs to verify (ops team, security team, etc.)
+
+## Optional Section Guidelines
+
+### Monitoring & Alerts
+- Include for any change that affects system observability
+- Document new dashboards, alerts, or metrics
+- Specify alert thresholds and escalation paths
+
+### Cost Impact
+- Include for changes that affect cloud spend
+- Document expected monthly cost change (before → after)
+- Include cost optimization considerations
+
+### Capacity Planning
+- Include for scaling-related changes
+- Document expected growth and headroom
+- Specify auto-scaling policies if applicable
+
+## Best Practices
+
+- Test infrastructure changes in a staging environment first
+- Include terraform/IaC references when applicable
+- Document the maintenance window if downtime is required
+- Keep rollback plans tested and up to date

package/templates/docs/spec-infrastructure/template.md

@@ -0,0 +1,71 @@
+---
+title: "{{title}}"
+fractary_doc_type: spec-infrastructure
+status: {{status}}
+date: {{date}}
+{{#work_id}}
+work_id: "{{work_id}}"
+{{/work_id}}
+{{#work_type}}
+work_type: {{work_type}}
+{{/work_type}}
+source: {{source}}
+validation_status: not_validated
+tags: []
+---
+
+# {{title}}
+
+## Objective
+
+{{objective}}
+
+## Current State
+
+{{current_state}}
+
+## Proposed Changes
+
+{{#changes}}
+- [ ] {{.}}
+{{/changes}}
+
+## Security Considerations
+
+{{security_considerations}}
+
+{{#monitoring}}
+## Monitoring & Alerts
+
+{{monitoring}}
+{{/monitoring}}
+
+{{#capacity}}
+## Capacity Planning
+
+{{capacity}}
+{{/capacity}}
+
+{{#cost_impact}}
+## Cost Impact
+
+{{cost_impact}}
+{{/cost_impact}}
+
+## Rollback Plan
+
+{{rollback_plan}}
+
+## Verification
+
+{{#verification_steps}}
+- [ ] {{.}}
+{{/verification_steps}}
+
+{{#dependencies}}
+## Dependencies
+
+{{#dependencies}}
+- {{.}}
+{{/dependencies}}
+{{/dependencies}}

package/templates/docs/spec-infrastructure/type.yaml

@@ -0,0 +1,102 @@
+id: spec-infrastructure
+display_name: Infrastructure Specification
+description: Specification for infrastructure and DevOps changes
+
+output_path: specs
+
+file_naming:
+  pattern: "WORK-{work_id}-{slug}.md"
+  auto_number: false
+  slug_source: title
+  slug_max_length: 50
+
+frontmatter:
+  required_fields:
+    - title
+    - fractary_doc_type
+    - status
+    - date
+  optional_fields:
+    - work_id
+    - work_type
+    - source
+    - validation_status
+    - tags
+    - author
+    - related
+    - changelog
+  defaults:
+    fractary_doc_type: spec-infrastructure
+    status: draft
+    source: conversation
+    validation_status: not_validated
+
+structure:
+  required_sections:
+    - Objective
+    - Current State
+    - Proposed Changes
+    - Security Considerations
+    - Rollback Plan
+    - Verification
+  optional_sections:
+    - Monitoring & Alerts
+    - Capacity Planning
+    - Cost Impact
+    - Dependencies
+    - References
+  section_order:
+    - Objective
+    - Current State
+    - Proposed Changes
+    - Security Considerations
+    - Monitoring & Alerts
+    - Capacity Planning
+    - Cost Impact
+    - Rollback Plan
+    - Verification
+    - Dependencies
+    - References
+
+status:
+  allowed_values:
+    - draft
+    - review
+    - approved
+    - in-progress
+    - completed
+    - archived
+  default: draft
+
+index_config:
+  index_file: specs/README.md
+  sort_by: date
+  sort_order: desc
+  entry_template: "- [**{{work_id}}**: {{title}}]({{relative_path}}) — {{status}}"
+
+archive:
+  enabled: true
+  source: archive
+  trigger: on_status_change
+  trigger_statuses:
+    - archived
+  verify_checksum: true
+  delete_original: true
+
+work_linking:
+  enabled: true
+  comment_on_create: true
+  comment_on_archive: true
+  require_closed_for_archive: true
+
+refinement:
+  enabled: true
+  post_questions_to_work_item: true
+  maintain_changelog: true
+
+fulfillment:
+  enabled: true
+  check_acceptance_criteria: false
+  check_files_modified: true
+  check_tests_added: false
+  check_docs_updated: true

package/templates/docs/standards/standards.md

@@ -0,0 +1,15 @@
+# Standards Documentation Standards
+
+## Required Conventions
+
+- ALWAYS include clear scope
+- ALWAYS provide examples
+- ALWAYS document exceptions
+- ALWAYS explain enforcement
+
+## Best Practices
+
+- Include good and bad examples
+- Version standards documents
+- Track changes in changelog
+- Reference external standards