@fractary/core 0.7.24 → 0.7.26

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}}

package/templates/logs/operational/type.yaml

@@ -0,0 +1,87 @@
+# Operational Log Type Definition
+#
+# This file defines the schema, frontmatter rules, and configuration
+# for operational and infrastructure log entries.
+
+id: operational
+display_name: Operational Log
+description: System events, service health, monitoring alerts, incident logs
+
+# Output configuration
+output_path: .fractary/logs/operational
+
+# File naming rules
+file_naming:
+  pattern: "{date}-{event_id}.md"
+  date_format: "YYYYMMDD-HHmmss"
+  slug_source: event_id
+  slug_max_length: 36
+
+# Frontmatter schema
+frontmatter:
+  required_fields:
+    - log_type
+    - title
+    - event_id
+    - date
+    - status
+    - service
+  optional_fields:
+    - severity
+    - category
+    - environment
+    - work_id
+    - tags
+  defaults:
+    log_type: operational
+    status: active
+
+# Document structure
+structure:
+  required_sections:
+    - Event Details
+    - Description
+  optional_sections:
+    - Impact
+    - Response Actions
+    - Resolution
+    - Follow-up
+  section_order:
+    - Event Details
+    - Description
+    - Impact
+    - Response Actions
+    - Resolution
+    - Follow-up
+
+# Status workflow
+status:
+  allowed_values:
+    - active
+    - investigating
+    - resolved
+    - archived
+  default: active
+
+# Severity levels
+severity:
+  allowed_values:
+    - info
+    - warning
+    - error
+    - critical
+  default: info
+
+# Category classification
+category:
+  allowed_values:
+    - health
+    - alert
+    - maintenance
+    - incident
+  default: health
+
+# Retention policy
+retention:
+  default_local_days: 30
+  default_cloud_days: 90

package/templates/logs/session/standards.md

@@ -0,0 +1,34 @@
+# Session Log Standards
+
+## Required Conventions
+
+### 1. Identification
+- ALWAYS generate UUID format session_id
+- ALWAYS include start timestamp
+- ALWAYS link to conversation_id when available
+
+### 2. Metadata Tracking
+- ALWAYS record model name
+- ALWAYS track token count
+- ALWAYS calculate duration on session stop
+
+### 3. Status Management
+- ALWAYS start sessions as active
+- ALWAYS mark stopped when capture ends
+- ALWAYS mark error if session fails
+
+### 4. Content Capture
+- ALWAYS capture conversation exchanges
+- ALWAYS include tool calls and results
+- ALWAYS summarize session outcomes
+
+## Best Practices
+
+- Use UUID format: `{uuid}` for session_id
+- Redact sensitive information (API keys, passwords)
+- Include repository and branch context
+- Link sessions to work items when applicable
+- Summarize key decisions made during session
+- Note follow-up actions identified
+- Archive sessions after 7 days locally
+- Keep cloud copies for historical reference

package/templates/logs/session/template.md

@@ -0,0 +1,81 @@
+---
+log_type: session
+title: {{title}}
+session_id: {{session_id}}
+date: {{date}}
+status: {{status}}
+{{#conversation_id}}
+conversation_id: {{conversation_id}}
+{{/conversation_id}}
+{{#repository}}
+repository: {{repository}}
+{{/repository}}
+{{#branch}}
+branch: {{branch}}
+{{/branch}}
+{{#model}}
+model: {{model}}
+{{/model}}
+{{#token_count}}
+token_count: {{token_count}}
+{{/token_count}}
+{{#duration_seconds}}
+duration_seconds: {{duration_seconds}}
+{{/duration_seconds}}
+{{#work_id}}
+work_id: {{work_id}}
+{{/work_id}}
+{{#tags}}
+tags:
+{{#tags}}
+  - {{.}}
+{{/tags}}
+{{/tags}}
+---
+
+# Session: {{title}}
+
+## Metadata
+
+- **Started**: {{date}}
+{{#model}}
+- **Model**: {{model}}
+{{/model}}
+{{#repository}}
+- **Repository**: {{repository}}
+{{/repository}}
+{{#branch}}
+- **Branch**: {{branch}}
+{{/branch}}
+{{#token_count}}
+- **Tokens**: {{token_count}}
+{{/token_count}}
+{{#duration_seconds}}
+- **Duration**: {{duration_seconds}}s
+{{/duration_seconds}}
+
+## Conversation
+
+{{conversation}}
+
+{{#summary}}
+## Summary
+
+{{summary}}
+{{/summary}}
+
+{{#decisions}}
+## Decisions
+
+{{#decisions}}
+- {{.}}
+{{/decisions}}
+{{/decisions}}
+
+{{#follow_ups}}
+## Follow-ups
+
+{{#follow_ups}}
+- {{.}}
+{{/follow_ups}}
+{{/follow_ups}}

package/templates/logs/session/type.yaml

@@ -0,0 +1,69 @@
+# Session Log Type Definition
+#
+# This file defines the schema, frontmatter rules, and configuration
+# for Claude Code session log entries.
+
+id: session
+display_name: Session Log
+description: Claude Code sessions, conversation tracking, token usage, interaction history
+
+# Output configuration
+output_path: .fractary/logs/sessions
+
+# File naming rules
+file_naming:
+  pattern: "{date}-{session_id}.md"
+  date_format: "YYYYMMDD-HHmmss"
+  slug_source: session_id
+  slug_max_length: 36
+
+# Frontmatter schema
+frontmatter:
+  required_fields:
+    - log_type
+    - title
+    - session_id
+    - date
+    - status
+  optional_fields:
+    - conversation_id
+    - repository
+    - branch
+    - model
+    - token_count
+    - duration_seconds
+    - work_id
+    - tags
+  defaults:
+    log_type: session
+    status: active
+
+# Document structure
+structure:
+  required_sections:
+    - Metadata
+    - Conversation
+  optional_sections:
+    - Summary
+    - Decisions
+    - Follow-ups
+  section_order:
+    - Metadata
+    - Conversation
+    - Summary
+    - Decisions
+    - Follow-ups
+
+# Status workflow
+status:
+  allowed_values:
+    - active
+    - stopped
+    - archived
+    - error
+  default: active
+
+# Retention policy
+retention:
+  default_local_days: 7
+  default_cloud_days: forever

package/templates/logs/test/standards.md

@@ -0,0 +1,34 @@
+# Test Log Standards
+
+## Required Conventions
+
+### 1. Identification
+- ALWAYS include unique test_id
+- ALWAYS specify test type (unit, integration, e2e, performance)
+- ALWAYS include test framework name
+
+### 2. Results Tracking
+- ALWAYS include pass/fail/skip counts
+- ALWAYS set status based on results (passed if all pass, failed if any fail)
+- ALWAYS include coverage percentage when available
+
+### 3. Failure Documentation
+- ALWAYS include error messages for failures
+- ALWAYS include stack traces when available
+- ALWAYS include test name that failed
+
+### 4. Output Capture
+- ALWAYS capture test runner output
+- ALWAYS preserve output formatting
+- ALWAYS truncate excessively long output with marker
+
+## Best Practices
+
+- Use unique test_id format: `TEST-{timestamp}-{random}`
+- Link test runs to CI/CD pipelines
+- Include environment information (Node version, etc.)
+- Track test flakiness over time
+- Keep failed test logs longer than passing
+- Archive test logs based on test type (e2e longer than unit)
+- Include screenshots for e2e test failures
+- Document known flaky tests

package/templates/logs/test/template.md

@@ -0,0 +1,83 @@
+---
+log_type: test
+title: {{title}}
+test_id: {{test_id}}
+date: {{date}}
+status: {{status}}
+{{#test_type}}
+test_type: {{test_type}}
+{{/test_type}}
+{{#test_framework}}
+test_framework: {{test_framework}}
+{{/test_framework}}
+{{#pass_count}}
+pass_count: {{pass_count}}
+{{/pass_count}}
+{{#fail_count}}
+fail_count: {{fail_count}}
+{{/fail_count}}
+{{#skip_count}}
+skip_count: {{skip_count}}
+{{/skip_count}}
+{{#coverage_percent}}
+coverage_percent: {{coverage_percent}}
+{{/coverage_percent}}
+{{#duration_seconds}}
+duration_seconds: {{duration_seconds}}
+{{/duration_seconds}}
+{{#work_id}}
+work_id: {{work_id}}
+{{/work_id}}
+{{#tags}}
+tags:
+{{#tags}}
+  - {{.}}
+{{/tags}}
+{{/tags}}
+---
+
+# Test Run: {{title}}
+
+## Summary
+
+- **Total**: {{total_count}}
+{{#pass_count}}
+- **Passed**: {{pass_count}}
+{{/pass_count}}
+{{#fail_count}}
+- **Failed**: {{fail_count}}
+{{/fail_count}}
+{{#skip_count}}
+- **Skipped**: {{skip_count}}
+{{/skip_count}}
+{{#coverage_percent}}
+- **Coverage**: {{coverage_percent}}%
+{{/coverage_percent}}
+{{#duration_seconds}}
+- **Duration**: {{duration_seconds}}s
+{{/duration_seconds}}
+
+{{#failures}}
+## Failures
+
+{{#failures}}
+### {{name}}
+
+- **Error**: {{error}}
+{{#stack}}
+- **Stack**:
+```
+{{stack}}
+```
+{{/stack}}
+
+{{/failures}}
+{{/failures}}
+
+{{#output}}
+## Output
+
+```
+{{output}}
+```
+{{/output}}

package/templates/logs/test/type.yaml

@@ -0,0 +1,75 @@
+# Test Log Type Definition
+#
+# This file defines the schema, frontmatter rules, and configuration
+# for test execution log entries.
+
+id: test
+display_name: Test Log
+description: Test runs, QA results, test failures, coverage reports, CI test output
+
+# Output configuration
+output_path: .fractary/logs/test
+
+# File naming rules
+file_naming:
+  pattern: "{date}-{test_id}.md"
+  date_format: "YYYYMMDD-HHmmss"
+  slug_source: test_id
+  slug_max_length: 36
+
+# Frontmatter schema
+frontmatter:
+  required_fields:
+    - log_type
+    - title
+    - test_id
+    - date
+    - status
+  optional_fields:
+    - test_type
+    - test_framework
+    - pass_count
+    - fail_count
+    - skip_count
+    - coverage_percent
+    - duration_seconds
+    - work_id
+    - tags
+  defaults:
+    log_type: test
+    status: running
+
+# Document structure
+structure:
+  required_sections:
+    - Summary
+  optional_sections:
+    - Failures
+    - Output
+  section_order:
+    - Summary
+    - Failures
+    - Output
+
+# Status workflow
+status:
+  allowed_values:
+    - running
+    - passed
+    - failed
+    - skipped
+  default: running
+
+# Test type classification
+test_type:
+  allowed_values:
+    - unit
+    - integration
+    - e2e
+    - performance
+  default: unit
+
+# Retention policy
+retention:
+  default_local_days: 7
+  default_cloud_days: 14

package/templates/logs/workflow/standards.md

@@ -0,0 +1,35 @@
+# Workflow Log Standards
+
+## Required Conventions
+
+### 1. Identification
+- ALWAYS use workflow-{id} format for workflow_id
+- ALWAYS specify workflow type (faber, etl, cicd, data-pipeline, custom)
+- ALWAYS link to work item when applicable
+
+### 2. Phase Tracking
+- ALWAYS track current FABER phase for faber workflows
+- ALWAYS record phase transitions
+- ALWAYS timestamp all operations
+
+### 3. Operation Logging
+- ALWAYS log operations with timestamps
+- ALWAYS include operation duration
+- ALWAYS track operation status
+
+### 4. Decision Documentation
+- ALWAYS document key decisions
+- ALWAYS include decision rationale
+- ALWAYS note alternatives considered
+
+## Best Practices
+
+- Use unique workflow_id format: `workflow-{timestamp}-{random}`
+- Track dependencies between workflows
+- Include context (project, repo, branch)
+- Record all artifacts created
+- Calculate and display metrics
+- Document next steps for continuation
+- Link related workflow logs
+- Archive completed workflows with metrics summary
+- Use partial status for workflows that partially succeed