ace-docs 0.31.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d8db3d8b6cb7383ccf27b9ae6ef604916a5ea45d3d5663d43eef658e97b3910
+  data.tar.gz: 8c504dacf7b471741762c0e008e5b8e3df924aa9aa4269438587bae3c2f7f457
+SHA512:
+  metadata.gz: e64eafe4114ff1f791258a428d7659807ce4bc7469386ffa540fcc2f632cc6127d25b9f378907afb2c8324f03a51d3daa93c71c75a0d67f24d8002408971a898
+  data.tar.gz: 8c8a4cd5c4e6838c6085eb33345a842a3ab60b24819ec9b6ad97009a0c7603a69481432ae73985f5b9e7b9e5e1a64951765236ce147760c8d879ff4dd989a21f

data/.ace-defaults/docs/config.yml

@@ -0,0 +1,169 @@
+# Configuration for ace-docs
+# This file uses FLAT structure for tool-specific config
+# as per ace-gems.g.md standards
+# Place this file at .ace/docs/config.yml in your project
+#
+# Note: Diff filtering is now handled by ace-git
+# Configure global diff settings at .ace/git/config.yml
+# Individual documents can specify paths/filters in their frontmatter
+
+# Cache directory for analysis reports
+cache_dir: .ace-local/docs
+
+# Analysis settings for LLM integration
+llm_temperature: 0.3  # Lower for deterministic compaction
+llm_timeout: 300      # Timeout in seconds for LLM requests (default: 300 = 5 minutes)
+# llm_model: gflash   # Override default if needed (commented to use ace-llm defaults)
+
+# Maximum diff lines before warning (context limit)
+max_diff_lines_warning: 100000
+
+# Multi-subject configuration example
+# Define multiple subjects to categorize changes separately
+# Place this in document frontmatter under ace-docs: section
+#
+# Example multi-subject configuration:
+#   ace-docs:
+#     context:
+#       files:
+#         - CHANGELOG.md
+#     subject:
+#       - code:
+#           diff:
+#             filters:
+#               - "**/*.rb"
+#       - config:
+#           diff:
+#             filters:
+#               - "**/*.yml"
+#               - "**/*.yaml"
+#       - docs:
+#           diff:
+#             filters:
+#               - "**/*.md"
+#
+# Single subject configuration (backward compatible):
+#   ace-docs:
+#     subject:
+#       diff:
+#         filters:
+#           - "**/*.rb"
+#           - "**/*.md"
+
+# Validation settings
+validation_enabled: true
+ace_lint_path: ace-lint  # Path to ace-lint executable
+
+# Document freshness thresholds (in days)
+# Frequency-specific thresholds that match historical defaults
+default_freshness_days:
+  # Daily documents: updated today is current, up to 2 days is stale
+  daily:
+    stale: 2
+  # Weekly documents: 7 days current, 14 days stale
+  weekly:
+    current: 7
+    stale: 14
+  # Monthly documents: 30 days current, 45 days stale
+  monthly:
+    current: 30
+    stale: 45
+
+# Document type definitions
+document_types:
+  # Core context documents
+  bundle:
+    paths:
+      - "docs/*.md"              # Core documentation
+      - "!docs/archive/**"       # Exclude archived docs
+    defaults:
+      update_frequency: weekly
+      max_lines: 150
+      required_sections:
+        - overview
+        - scope
+
+  # Development guides
+  guide:
+    paths:
+      - "**/*.g.md"              # Extension-based pattern
+    guide: "guide://documentation"
+    defaults:
+      update_frequency: monthly
+      max_lines: 500
+
+  # Workflow instructions
+  workflow:
+    paths:
+      - "**/*.wf.md"             # Extension pattern
+    guide: "guide://documentation"
+    defaults:
+      update_frequency: on-change
+      auto_generate:
+        - template-refs: from-embedded
+
+  # Monorepo root README
+  root_readme:
+    paths:
+      - "README.md"
+    guide: "guide://documentation"
+    defaults:
+      update_frequency: on-change
+      max_lines: 2000
+
+  # Package READMEs
+  readme:
+    paths:
+      - "*/README.md"
+    template: "tmpl://project-docs/README"
+    guide: "guide://documentation"
+    defaults:
+      update_frequency: on-change
+      max_lines: 1200
+
+  # User-facing documentation (non-README)
+  user:
+    paths:
+      - "*/docs/**/*.md"
+    defaults:
+      update_frequency: on-change
+      max_lines: 1200
+
+  # Templates
+  template:
+    paths:
+      - "**/*.template.md"
+    defaults:
+      update_frequency: on-change
+      max_lines: 200
+
+  # Reference documentation
+  reference:
+    paths:
+      - "*/docs/reference/*.md"
+      - "reference/**/*.md"
+    defaults:
+      update_frequency: monthly
+      max_lines: 1000
+
+# Global validation rules (merged with type-specific, type wins)
+global_rules:
+  max_lines: 1000              # Default maximum lines
+  required_frontmatter:
+    - doc-type
+    - purpose
+
+# Ignored paths
+ignore:
+  - "**/node_modules/**"
+  - "**/vendor/**"
+  - "**/.git/**"
+  - "**/tmp/**"
+  - "**/coverage/**"
+  - "**/_legacy/**"
+  - "**/.ace-tasks/done/**"
+
+# Files managed without YAML frontmatter.
+frontmatter_free:
+  - "README.md"
+  - "*/README.md"

data/.ace-defaults/docs/multi-subject-example.md

@@ -0,0 +1,130 @@
+---
+doc-type: reference
+purpose: Example document demonstrating multi-subject configuration
+ace-docs:
+  # Context configuration - files to include for understanding
+  bundle:
+    files:
+      - CHANGELOG.md
+      - README.md
+    preset: project-base  # Use ace-bundle preset if available
+
+  # Multi-subject configuration - categorize changes by type
+  # Each subject generates its own diff file for focused analysis
+  subject:
+    # Code changes - Ruby implementation files
+    - code:
+        diff:
+          filters:
+            - "lib/**/*.rb"           # Library code
+            - "app/**/*.rb"           # Application code
+            - "test/**/*.rb"          # Test files
+            - "spec/**/*.rb"          # RSpec tests
+
+    # Configuration changes - YAML and JSON files
+    - config:
+        diff:
+          filters:
+            - "**/*.yml"              # YAML config files
+            - "**/*.yaml"             # Alternative YAML extension
+            - "**/*.json"             # JSON config files
+            - ".ace/**/*"             # ACE configuration
+            - "config/**/*"           # Config directory
+
+    # Documentation changes - Markdown and text files
+    - docs:
+        diff:
+          filters:
+            - "**/*.md"               # Markdown documentation
+            - "docs/**/*"             # Documentation directory
+            - "README*"               # README files
+            - "CHANGELOG*"            # Changelog files
+            - "*.txt"                 # Text files
+
+# Update tracking
+update:
+  frequency: weekly
+  last-updated: 2025-10-20
+---
+
+# Multi-Subject Configuration Example
+
+This example demonstrates how to use **multi-subject configuration** in ace-docs to generate separate diff files for different categories of changes.
+
+## Benefits of Multi-Subject Configuration
+
+1. **Focused Analysis**: Each subject (code, config, docs) gets its own diff file, allowing for targeted analysis
+2. **Reduced Noise**: Documentation changes don't clutter code change analysis
+3. **Better Context**: LLM can analyze each type of change with appropriate context
+4. **Cleaner Reports**: Analysis reports are organized by change category
+
+## How It Works
+
+When you run `ace-docs analyze` on this document:
+
+```bash
+ace-docs analyze multi-subject-example.md
+```
+
+The system will:
+
+1. Generate three separate diff files:
+   - `code.diff` - Contains only Ruby file changes
+   - `config.diff` - Contains configuration file changes
+   - `docs.diff` - Contains documentation changes
+
+2. Each diff is filtered according to the patterns specified in the `filters` array
+
+3. The LLM receives all three diffs and can provide dual-mode analysis:
+   - Technical analysis for code changes
+   - Configuration impact analysis
+   - Documentation coverage assessment
+
+## Configuration Details
+
+### Subject Structure
+
+Each subject is defined as a single-key object where:
+- The key is the subject name (e.g., "code", "config", "docs")
+- The value contains a `diff` object with `filters` array
+
+```yaml
+- code:                    # Subject name
+    diff:                  # Diff configuration
+      filters:             # Array of glob patterns
+        - "**/*.rb"
+```
+
+### Filter Patterns
+
+Filters use glob patterns compatible with git pathspecs:
+- `**/*.rb` - All Ruby files in any directory
+- `lib/**/*.rb` - Ruby files under lib/ directory
+- `config/**/*` - All files under config/ directory
+- `README*` - Files starting with README
+
+### Custom Subject Names
+
+You can use any subject names that make sense for your project:
+
+```yaml
+subject:
+  - frontend:
+      diff:
+        filters:
+          - "src/**/*.tsx"
+          - "src/**/*.ts"
+  - backend:
+      diff:
+        filters:
+          - "api/**/*.py"
+  - infrastructure:
+      diff:
+        filters:
+          - "terraform/**/*.tf"
+          - "k8s/**/*.yaml"
+```
+
+## Backward Compatibility
+
+Multi-subject configuration is fully backward compatible. Single-subject documents continue to work without modification.

data/.ace-defaults/docs/single-subject-example.md

@@ -0,0 +1,150 @@
+---
+doc-type: guide
+purpose: Example document demonstrating single-subject configuration (backward compatible)
+ace-docs:
+  # Context configuration
+  bundle:
+    files:
+      - README.md
+    keywords:
+      - architecture
+      - design patterns
+
+  # Single-subject configuration - all changes in one diff
+  # This is the traditional format, still fully supported
+  subject:
+    diff:
+      filters:
+        - "lib/**/*.rb"        # Ruby library files
+        - "app/**/*.rb"        # Ruby application files
+        - "**/*.md"            # All markdown files
+        - "config/**/*.yml"    # Configuration files
+
+  # Validation rules
+  rules:
+    max-lines: 500
+    sections:
+      - overview
+      - usage
+      - examples
+
+# Update tracking
+update:
+  frequency: monthly
+  last-updated: 2025-10-20
+---
+
+# Single-Subject Configuration Example
+
+This example demonstrates the **traditional single-subject configuration** which remains fully supported for backward compatibility.
+
+## Overview
+
+The single-subject configuration generates one consolidated diff file (`repo-diff.diff`) containing all changes that match any of the specified filters. This is the original ace-docs behavior and continues to work without any modifications needed.
+
+## Usage
+
+When you run `ace-docs analyze` on this document:
+
+```bash
+ace-docs analyze single-subject-example.md
+```
+
+The system will:
+1. Generate a single `repo-diff.diff` file containing all changes matching the filters
+2. Include changes from Ruby files, markdown files, and YAML configs in one diff
+3. Provide unified analysis of all changes together
+
+## Configuration Format
+
+The single-subject format uses a direct `diff` object under `subject`:
+
+```yaml
+ace-docs:
+  subject:
+    diff:
+      filters:
+        - "**/*.rb"
+        - "**/*.md"
+        - "**/*.yml"
+```
+
+## When to Use Single-Subject
+
+Single-subject configuration is ideal when:
+
+1. **Small Projects**: Your project has a limited number of files
+2. **Unified Analysis**: You want all changes analyzed together
+3. **Simple Requirements**: You don't need to separate different types of changes
+4. **Legacy Compatibility**: You have existing documents that already use this format
+
+## Examples
+
+### Minimal Configuration
+
+```yaml
+ace-docs:
+  subject:
+    diff:
+      filters:
+        - "src/**/*"  # Everything under src/
+```
+
+### Specific File Types
+
+```yaml
+ace-docs:
+  subject:
+    diff:
+      filters:
+        - "**/*.rb"
+        - "**/*.erb"
+        - "**/*.rake"
+```
+
+### Exclude Patterns
+
+While ace-docs doesn't directly support exclude patterns, you can achieve similar results by being specific with your include patterns:
+
+```yaml
+ace-docs:
+  subject:
+    diff:
+      filters:
+        - "app/**/*.rb"     # Only app Ruby files
+        - "lib/**/*.rb"     # Only lib Ruby files
+        # Implicitly excludes test/**/*.rb
+```
+
+## Migration to Multi-Subject
+
+If you later want to migrate to multi-subject configuration, you can split your filters into categories:
+
+**Before (Single-Subject):**
+```yaml
+subject:
+  diff:
+    filters:
+      - "**/*.rb"
+      - "**/*.md"
+      - "**/*.yml"
+```
+
+**After (Multi-Subject):**
+```yaml
+subject:
+  - code:
+      diff:
+        filters:
+          - "**/*.rb"
+  - docs:
+      diff:
+        filters:
+          - "**/*.md"
+  - config:
+      diff:
+        filters:
+          - "**/*.yml"
+```
+
+Both configurations are valid and you can choose based on your needs.

data/.ace-defaults/nav/protocols/guide-sources/ace-docs.yml

@@ -0,0 +1,10 @@
+---
+# Guide Sources Protocol Configuration for ace-docs gem
+name: ace-docs
+type: gem
+description: Guides from ace-docs gem
+priority: 10
+config:
+  relative_path: handbook/guides
+  pattern: "*.g.md"
+  enabled: true

data/.ace-defaults/nav/protocols/prompt-sources/ace-docs.yml

@@ -0,0 +1,34 @@
+---
+# Prompt Sources Protocol Configuration for ace-docs gem
+# This enables prompt discovery from the installed ace-docs gem
+
+name: ace-docs
+type: gem
+description: Documentation analysis prompts from ace-docs gem
+priority: 10
+
+# Configuration for prompt discovery within the gem
+config:
+  # Relative path within the gem (default: handbook/prompts)
+  relative_path: handbook/prompts
+
+  # Pattern for finding prompt files (supports both *.md and *.prompt.md)
+  pattern: "*.md"
+
+  # Enable discovery
+  enabled: true
+
+# Categories of prompts available
+categories:
+  - document-analysis  # System prompts for documentation analysis
+
+# Notes for users
+notes: |
+  ace-docs provides prompts for documentation analysis:
+  - document-analysis.system: Main system prompt for analyzing code changes
+    and determining documentation updates
+
+  Use prompt:// URIs to reference these prompts in your analysis configurations.
+  Users can override by creating:
+    - .ace-handbook/prompts/document-analysis.system.md (project)
+    - ~/.ace-handbook/prompts/document-analysis.system.md (user)

data/.ace-defaults/nav/protocols/tmpl-sources/ace-docs.yml

@@ -0,0 +1,10 @@
+---
+# Template Sources Protocol Configuration for ace-docs gem
+name: ace-docs
+type: gem
+description: Templates from ace-docs gem
+priority: 10
+config:
+  relative_path: handbook/templates
+  pattern: "**/*.template.md"
+  enabled: true

data/.ace-defaults/nav/protocols/wfi-sources/ace-docs.yml

@@ -0,0 +1,19 @@
+---
+# WFI Sources Protocol Configuration for ace-review gem
+# This enables workflow discovery from the installed ace-review gem
+
+name: ace-docs
+type: gem
+description: Docs management from ace-docs gem
+priority: 10
+
+# Configuration for workflow discovery within the gem
+config:
+  # Relative path within the gem (default: handbook/workflow-instructions)
+  relative_path: handbook/workflow-instructions
+
+  # Pattern for finding workflow files (default: *.wf.md)
+  pattern: "*.wf.md"
+
+  # Enable discovery
+  enabled: true