@fractary/core 0.7.23 → 0.7.25

package/templates/logs/changelog/template.md

@@ -0,0 +1,71 @@
+---
+log_type: changelog
+title: {{title}}
+change_id: {{change_id}}
+date: {{date}}
+version: {{version}}
+change_type: {{change_type}}
+{{#breaking}}
+breaking: {{breaking}}
+{{/breaking}}
+{{#component}}
+component: {{component}}
+{{/component}}
+{{#issue_number}}
+issue_number: {{issue_number}}
+{{/issue_number}}
+{{#work_id}}
+work_id: {{work_id}}
+{{/work_id}}
+{{#tags}}
+tags:
+{{#tags}}
+  - {{.}}
+{{/tags}}
+{{/tags}}
+---
+
+# Change: {{title}}
+
+## Summary
+
+{{summary}}
+
+## Type: {{change_type}}
+
+**Breaking Change**: {{#breaking}}Yes{{/breaking}}{{^breaking}}No{{/breaking}}
+
+## Details
+
+{{details}}
+
+{{#migration}}
+## Migration
+
+{{migration}}
+{{/migration}}
+
+{{#before_after}}
+## Before/After
+
+**Before**:
+```
+{{before}}
+```
+
+**After**:
+```
+{{after}}
+```
+{{/before_after}}
+
+{{#related}}
+## Related
+
+{{#issue_number}}
+- Issue: #{{issue_number}}
+{{/issue_number}}
+{{#pr_number}}
+- PR: #{{pr_number}}
+{{/pr_number}}
+{{/related}}

package/templates/logs/changelog/type.yaml

@@ -0,0 +1,70 @@
+# Changelog Log Type Definition
+#
+# This file defines the schema, frontmatter rules, and configuration
+# for change tracking log entries.
+
+id: changelog
+display_name: Changelog Log
+description: Version changes, feature updates, release notes, configuration changes
+
+# Output configuration
+output_path: .fractary/logs/changelog
+
+# File naming rules
+file_naming:
+  pattern: "{date}-{change_id}.md"
+  date_format: "YYYYMMDD-HHmmss"
+  slug_source: change_id
+  slug_max_length: 36
+
+# Frontmatter schema
+frontmatter:
+  required_fields:
+    - log_type
+    - title
+    - change_id
+    - date
+    - version
+    - change_type
+  optional_fields:
+    - breaking
+    - component
+    - issue_number
+    - work_id
+    - tags
+  defaults:
+    log_type: changelog
+    breaking: false
+
+# Document structure
+structure:
+  required_sections:
+    - Summary
+    - Details
+  optional_sections:
+    - Migration
+    - Before/After
+    - Related
+  section_order:
+    - Summary
+    - Type
+    - Details
+    - Migration
+    - Before/After
+    - Related
+
+# Change type classification
+change_type:
+  allowed_values:
+    - added
+    - changed
+    - fixed
+    - removed
+    - deprecated
+    - security
+  default: changed
+
+# Retention policy
+retention:
+  default_local_days: forever
+  default_cloud_days: forever

package/templates/logs/debug/standards.md

@@ -0,0 +1,33 @@
+# Debug Log Standards
+
+## Required Conventions
+
+### 1. Problem Documentation
+- ALWAYS describe the problem clearly and completely
+- ALWAYS include error messages and stack traces
+- ALWAYS note the environment where the issue occurs
+
+### 2. Investigation Tracking
+- ALWAYS timestamp investigation steps
+- ALWAYS document what was tried (even if unsuccessful)
+- ALWAYS note hypotheses and their outcomes
+
+### 3. Status Management
+- ALWAYS update status as debugging progresses
+- ALWAYS mark as resolved when root cause found and fixed
+- ALWAYS link to related issues/PRs
+
+### 4. Knowledge Capture
+- ALWAYS document the root cause when identified
+- ALWAYS include resolution steps for future reference
+- ALWAYS note if issue might recur
+
+## Best Practices
+
+- Use unique debug_id format: `DEBUG-{timestamp}-{random}`
+- Include reproduction steps when possible
+- Attach relevant log snippets and screenshots
+- Link to related debugging sessions
+- Set severity based on impact (critical for production issues)
+- Archive resolved sessions after 14 days
+- Cross-reference with similar issues in the codebase

package/templates/logs/debug/template.md

@@ -0,0 +1,63 @@
+---
+log_type: debug
+title: {{title}}
+debug_id: {{debug_id}}
+date: {{date}}
+status: {{status}}
+{{#issue_number}}
+issue_number: {{issue_number}}
+{{/issue_number}}
+{{#component}}
+component: {{component}}
+{{/component}}
+{{#severity}}
+severity: {{severity}}
+{{/severity}}
+{{#repository}}
+repository: {{repository}}
+{{/repository}}
+{{#branch}}
+branch: {{branch}}
+{{/branch}}
+{{#work_id}}
+work_id: {{work_id}}
+{{/work_id}}
+{{#tags}}
+tags:
+{{#tags}}
+  - {{.}}
+{{/tags}}
+{{/tags}}
+---
+
+# Debug: {{title}}
+
+## Problem Description
+
+{{problem_description}}
+
+## Investigation Steps
+
+{{#investigation_steps}}
+1. {{.}}
+{{/investigation_steps}}
+
+{{#findings}}
+## Findings
+
+{{#findings}}
+- {{.}}
+{{/findings}}
+{{/findings}}
+
+{{#root_cause}}
+## Root Cause
+
+{{root_cause}}
+{{/root_cause}}
+
+{{#resolution}}
+## Resolution
+
+{{resolution}}
+{{/resolution}}

package/templates/logs/debug/type.yaml

@@ -0,0 +1,77 @@
+# Debug Log Type Definition
+#
+# This file defines the schema, frontmatter rules, and configuration
+# for debug session log entries.
+
+id: debug
+display_name: Debug Log
+description: Troubleshooting, bug investigation, error analysis, debugging notes
+
+# Output configuration
+output_path: .fractary/logs/debug
+
+# File naming rules
+file_naming:
+  pattern: "{date}-{debug_id}.md"
+  date_format: "YYYYMMDD-HHmmss"
+  slug_source: debug_id
+  slug_max_length: 36
+
+# Frontmatter schema
+frontmatter:
+  required_fields:
+    - log_type
+    - title
+    - debug_id
+    - date
+    - status
+  optional_fields:
+    - issue_number
+    - component
+    - severity
+    - repository
+    - branch
+    - work_id
+    - tags
+  defaults:
+    log_type: debug
+    status: active
+
+# Document structure
+structure:
+  required_sections:
+    - Problem Description
+    - Investigation Steps
+  optional_sections:
+    - Findings
+    - Root Cause
+    - Resolution
+  section_order:
+    - Problem Description
+    - Investigation Steps
+    - Findings
+    - Root Cause
+    - Resolution
+
+# Status workflow
+status:
+  allowed_values:
+    - active
+    - stopped
+    - resolved
+    - archived
+  default: active
+
+# Severity levels
+severity:
+  allowed_values:
+    - low
+    - medium
+    - high
+    - critical
+  default: medium
+
+# Retention policy
+retention:
+  default_local_days: 14
+  default_cloud_days: 30

package/templates/logs/deployment/standards.md

@@ -0,0 +1,34 @@
+# Deployment Log Standards
+
+## Required Conventions
+
+### 1. Identification
+- ALWAYS include unique deployment_id
+- ALWAYS specify target environment
+- ALWAYS include version and commit SHA
+
+### 2. Status Tracking
+- ALWAYS update status as deployment progresses
+- ALWAYS record start and end times
+- ALWAYS calculate total duration
+
+### 3. Verification
+- ALWAYS include verification checklist
+- ALWAYS document health check results
+- ALWAYS note any manual verification steps
+
+### 4. Rollback Documentation
+- ALWAYS document rollback procedure before deployment
+- ALWAYS mark status as rolled_back if reverting
+- ALWAYS include reason for rollback
+
+## Best Practices
+
+- Use unique deployment_id format: `DEPLOY-{timestamp}-{random}`
+- Include pre-deployment checklist completion
+- Document any configuration changes
+- Link to CI/CD pipeline run
+- Record who approved/triggered the deployment
+- Keep production deployment logs indefinitely
+- Include metrics before and after deployment
+- Document any incidents during deployment

package/templates/logs/deployment/template.md

@@ -0,0 +1,64 @@
+---
+log_type: deployment
+title: {{title}}
+deployment_id: {{deployment_id}}
+date: {{date}}
+status: {{status}}
+environment: {{environment}}
+{{#version}}
+version: {{version}}
+{{/version}}
+{{#commit_sha}}
+commit_sha: {{commit_sha}}
+{{/commit_sha}}
+{{#deployment_tool}}
+deployment_tool: {{deployment_tool}}
+{{/deployment_tool}}
+{{#duration_seconds}}
+duration_seconds: {{duration_seconds}}
+{{/duration_seconds}}
+{{#work_id}}
+work_id: {{work_id}}
+{{/work_id}}
+{{#tags}}
+tags:
+{{#tags}}
+  - {{.}}
+{{/tags}}
+{{/tags}}
+---
+
+# Deployment: {{title}}
+
+## Configuration
+
+- **Environment**: {{environment}}
+{{#version}}
+- **Version**: {{version}}
+{{/version}}
+{{#commit_sha}}
+- **Commit**: {{commit_sha}}
+{{/commit_sha}}
+{{#deployment_tool}}
+- **Tool**: {{deployment_tool}}
+{{/deployment_tool}}
+
+## Deployment Steps
+
+{{#deployment_steps}}
+1. {{.}}
+{{/deployment_steps}}
+
+{{#verification}}
+## Verification
+
+{{#verification_checks}}
+- [ ] {{.}}
+{{/verification_checks}}
+{{/verification}}
+
+{{#summary}}
+## Summary
+
+{{summary}}
+{{/summary}}

package/templates/logs/deployment/type.yaml

@@ -0,0 +1,76 @@
+# Deployment Log Type Definition
+#
+# This file defines the schema, frontmatter rules, and configuration
+# for deployment and release log entries.
+
+id: deployment
+display_name: Deployment Log
+description: Production deploys, staging releases, rollbacks, environment updates
+
+# Output configuration
+output_path: .fractary/logs/deployment
+
+# File naming rules
+file_naming:
+  pattern: "{date}-{deployment_id}.md"
+  date_format: "YYYYMMDD-HHmmss"
+  slug_source: deployment_id
+  slug_max_length: 36
+
+# Frontmatter schema
+frontmatter:
+  required_fields:
+    - log_type
+    - title
+    - deployment_id
+    - date
+    - status
+    - environment
+  optional_fields:
+    - version
+    - commit_sha
+    - deployment_tool
+    - duration_seconds
+    - work_id
+    - tags
+  defaults:
+    log_type: deployment
+    status: pending
+
+# Document structure
+structure:
+  required_sections:
+    - Configuration
+    - Deployment Steps
+  optional_sections:
+    - Verification
+    - Summary
+  section_order:
+    - Configuration
+    - Deployment Steps
+    - Verification
+    - Summary
+
+# Status workflow
+status:
+  allowed_values:
+    - pending
+    - deploying
+    - success
+    - failure
+    - rolled_back
+  default: pending
+
+# Environment classification
+environment:
+  allowed_values:
+    - development
+    - staging
+    - production
+    - test
+  default: staging
+
+# Retention policy
+retention:
+  default_local_days: 30
+  default_cloud_days: forever

package/templates/logs/manifest.yaml

@@ -0,0 +1,70 @@
+# Core Log Types Manifest
+#
+# This manifest lists all core log types available in Fractary.
+# The format matches .fractary/config.yaml's logs.custom_types section,
+# so users can extend with their own types using the same structure.
+#
+# Each type is a directory containing:
+#   - type.yaml     : Type definition (schema, frontmatter rules, file naming)
+#   - template.md   : Mustache template for log generation
+#   - standards.md  : Standards and conventions for this type
+
+version: "1.0"
+
+# Base URL for raw file access (used by remote tools/SDKs)
+base_url: https://raw.githubusercontent.com/fractary/core/main/templates/logs
+
+log_types:
+  - id: audit
+    display_name: Audit Log
+    description: Security events, access logs, compliance tracking, change audits
+    path: ./audit
+    url: ${base_url}/audit/type.yaml
+
+  - id: build
+    display_name: Build Log
+    description: CI/CD builds, compilation output, npm/cargo/make builds, build failures
+    path: ./build
+    url: ${base_url}/build/type.yaml
+
+  - id: changelog
+    display_name: Changelog Log
+    description: Version changes, feature updates, release notes, configuration changes
+    path: ./changelog
+    url: ${base_url}/changelog/type.yaml
+
+  - id: debug
+    display_name: Debug Log
+    description: Troubleshooting, bug investigation, error analysis, debugging notes
+    path: ./debug
+    url: ${base_url}/debug/type.yaml
+
+  - id: deployment
+    display_name: Deployment Log
+    description: Production deploys, staging releases, rollbacks, environment updates
+    path: ./deployment
+    url: ${base_url}/deployment/type.yaml
+
+  - id: operational
+    display_name: Operational Log
+    description: System events, service health, monitoring alerts, incident logs
+    path: ./operational
+    url: ${base_url}/operational/type.yaml
+
+  - id: session
+    display_name: Session Log
+    description: Claude Code sessions, conversation tracking, token usage, interaction history
+    path: ./session
+    url: ${base_url}/session/type.yaml
+
+  - id: test
+    display_name: Test Log
+    description: Test runs, QA results, test failures, coverage reports, CI test output
+    path: ./test
+    url: ${base_url}/test/type.yaml
+
+  - id: workflow
+    display_name: Workflow Log
+    description: FABER phases, ETL pipelines, data workflows, automation steps
+    path: ./workflow
+    url: ${base_url}/workflow/type.yaml

package/templates/logs/operational/standards.md

@@ -0,0 +1,34 @@
+# Operational Log Standards
+
+## Required Conventions
+
+### 1. Event Identification
+- ALWAYS include unique event_id
+- ALWAYS specify affected service
+- ALWAYS include detection timestamp
+
+### 2. Classification
+- ALWAYS set appropriate severity (info, warning, error, critical)
+- ALWAYS categorize event (health, alert, maintenance, incident)
+- ALWAYS specify environment (dev, staging, prod)
+
+### 3. Impact Assessment
+- ALWAYS document user and system impact
+- ALWAYS note scope of impact (partial, full outage)
+- ALWAYS estimate number of affected users if applicable
+
+### 4. Response Documentation
+- ALWAYS document actions taken
+- ALWAYS include timestamps for response actions
+- ALWAYS note who responded
+
+## Best Practices
+
+- Use unique event_id format: `OP-{timestamp}-{random}`
+- Link to monitoring dashboards and alerts
+- Include relevant metrics and graphs
+- Track MTTR (Mean Time to Recovery) for incidents
+- Document post-incident action items
+- Escalate critical events immediately
+- Create postmortem documents for major incidents
+- Keep production incident logs for compliance

package/templates/logs/operational/template.md

@@ -0,0 +1,71 @@
+---
+log_type: operational
+title: {{title}}
+event_id: {{event_id}}
+date: {{date}}
+status: {{status}}
+service: {{service}}
+{{#severity}}
+severity: {{severity}}
+{{/severity}}
+{{#category}}
+category: {{category}}
+{{/category}}
+{{#environment}}
+environment: {{environment}}
+{{/environment}}
+{{#work_id}}
+work_id: {{work_id}}
+{{/work_id}}
+{{#tags}}
+tags:
+{{#tags}}
+  - {{.}}
+{{/tags}}
+{{/tags}}
+---
+
+# Operational Event: {{title}}
+
+## Event Details
+
+- **Service**: {{service}}
+{{#severity}}
+- **Severity**: {{severity}}
+{{/severity}}
+{{#category}}
+- **Category**: {{category}}
+{{/category}}
+- **Detected**: {{date}}
+
+## Description
+
+{{description}}
+
+{{#impact}}
+## Impact
+
+{{impact}}
+{{/impact}}
+
+{{#response_actions}}
+## Response Actions
+
+{{#response_actions}}
+1. {{.}}
+{{/response_actions}}
+{{/response_actions}}
+
+{{#resolution}}
+## Resolution
+
+{{resolution}}
+{{/resolution}}
+
+{{#follow_up}}
+## Follow-up
+
+{{#follow_up}}
+- {{.}}
+{{/follow_up}}
+{{/follow_up}}