ace-docs 0.31.0

data/handbook/workflow-instructions/docs/update.wf.md

@@ -0,0 +1,418 @@
+---
+doc-type: workflow
+title: Update Documentation with ace-docs
+purpose: Update documentation with ace-docs tool orchestration
+ace-docs:
+  last-updated: 2026-03-08
+  last-checked: 2026-03-21
+---
+
+# Update Documentation with ace-docs
+
+Orchestrate ace-docs tools for iterative documentation updates through agent/human collaboration.
+
+## Quick Start
+
+### Specific File Update (Direct Path)
+
+When updating a specific document, go straight to analysis:
+
+```bash
+# Analyze specific document immediately
+ace-docs analyze docs/api.md
+
+# Review the analysis report
+cat .ace-local/docs/analyze-*/analysis.md
+
+# Update document based on recommendations
+ace-docs update docs/api.md --set last-updated=today
+```
+
+### Bulk Update (Status Check First)
+
+When updating multiple documents or checking what needs updates:
+
+```bash
+# Check which documents need updates
+ace-docs status --needs-update
+
+# Analyze all documents needing updates
+ace-docs analyze --needs-update
+
+# Review analysis report and update documents
+cat .ace-local/docs/analyze-*/analysis.md
+ace-docs update [file] --set last-updated=today
+
+# Or filter by type
+ace-docs status --type guide
+ace-docs analyze --all --type guide
+
+# Scope to one package
+ace-docs status --package ace-assign
+ace-docs validate --package ace-assign --all
+
+# Scope with glob (bare package path is normalized)
+ace-docs status --glob ace-assign
+ace-docs validate --glob "ace-assign/docs/**/*.md" --syntax
+```
+
+## Input Handling
+
+Accept flexible input for document selection:
+
+### Direct Analysis (Skip Status Check)
+
+When specific file(s) are provided, the workflow proceeds directly to analysis:
+
+1. **Specific documents**: List of file paths
+   - `docs/api.md handbook/guide.md`
+   - Goes straight to `ace-docs analyze [files]`
+
+### Status-First (Check What Needs Updates)
+
+When using filters or bulk operations, the workflow starts with status check:
+
+2. **Preset selection**: Use configured preset
+   - `--preset standard`
+3. **Type filtering**: Update by document type
+   - `--type guide`
+4. **Scope filtering**: Restrict by package or path glob
+   - `--package ace-assign`
+   - `--glob ace-assign` (normalized to `ace-assign/**/*.md`)
+   - `--glob "ace-assign/docs/**/*.md"`
+5. **Status-based**: Documents needing update
+   - `--needs-update` (default when no files specified)
+6. **All documents**: Process everything
+   - `--all`
+
+**Decision Rule**: If specific file paths are provided → skip to analysis. Otherwise → start with status check.
+
+## Workflow Steps
+
+### Decision Point: Specific File or Bulk Operation?
+
+**If specific file(s) provided** → Skip to Step 2 (Analyze Documents)
+**If bulk/filter operation** → Start at Step 1 (Load Document Status)
+
+### 1. Load Document Status (Bulk Operations Only)
+
+**Skip this step if specific file(s) were provided.**
+
+For bulk operations, check current state of managed documents:
+
+```bash
+ace-docs status [options]
+```
+
+Review the table showing:
+- Document names and types
+- Last updated dates
+- Freshness status (current/stale/outdated)
+- Update frequency configuration
+
+If no documents match criteria, exit with message.
+
+### 2. Analyze Documents (Always Required)
+
+Generate LLM-powered analysis for selected documents:
+
+```bash
+ace-docs analyze [file|--all|--needs-update] [options]
+```
+
+Options:
+- `--since DATE`: Analyze from specific date/commit
+- `--exclude-renames`: Skip renamed files
+- `--exclude-moves`: Skip moved files
+
+The analysis is saved to `.ace-local/docs/analyze-{timestamp}/analysis.md`
+
+**Note**: The analyze directory contains additional files (context.md, *.diff, prompts) for debugging purposes only. The workflow uses `analysis.md` as the primary output.
+
+**Decision Point**: If no changes detected, exit workflow.
+
+### 2.5 Review Analysis Report
+
+Read the generated analysis report:
+
+```bash
+cat .ace-local/docs/analyze-*/analysis.md
+```
+
+The report contains:
+- **Summary**: Overview of changes affecting the document
+- **Changes Detected**: Categorized by priority (HIGH/MEDIUM/LOW)
+- **Recommended Updates**: Specific sections to update with reasoning
+- **Additional Notes**: Context and patterns to consider
+
+Use these LLM recommendations to guide your document updates in the next step.
+
+### 3. Review and Update Documents
+
+For each document with changes:
+
+#### a. Load Document Context
+- Read current document content
+- Review frontmatter configuration
+- Note update focus areas if specified
+
+#### b. Apply Analysis Recommendations
+Using the analysis.md report:
+- Focus on HIGH priority changes first
+- Review specific "Recommended Updates" for the document
+- Consider the reasoning provided for each recommendation
+- Maintain document style while incorporating changes
+
+#### c. Update Document Content
+**Agent/Human Decision**: Based on changes:
+- Update technical details
+- Add new sections
+- Remove outdated information
+- Maintain document style/voice
+
+#### d. Update Metadata
+After content updates:
+
+```bash
+ace-docs update [file] --set last-updated=today --set last-checked=today
+```
+
+Additional metadata updates:
+- Version numbers if applicable
+- Custom metadata fields
+- Context requirements
+
+### 4. Validate Updates
+
+Run validation on updated documents:
+
+```bash
+ace-docs validate [file|pattern] [--syntax|--semantic|--all]
+```
+
+Check for:
+- Required frontmatter fields
+- Max line limits
+- Required sections
+- Syntax errors (if linter available)
+- Semantic issues (if LLM available)
+
+### 5. Present Summary
+
+Generate summary of updates:
+- Number of documents updated
+- Types of changes made
+- Any validation issues
+- Documents skipped/deferred
+
+## Document-Specific Guidelines
+
+### Tool Documentation (tools.md, reference docs)
+
+When updating tool documentation and command references:
+
+**Best Practices for Examples:**
+- Only include meaningful, practical examples that demonstrate real usage
+- Skip trivial commands like `--version`, `--help`, `-h`, `-v`
+- Show actual usage that demonstrates the tool's purpose
+- Aim for 2-4 practical examples per tool
+- Focus on common use cases and workflows
+
+**Example - Good:**
+```bash
+# Analyze documents needing updates
+ace-docs status --needs-update
+
+# Update specific document metadata
+ace-docs update docs/api.md --set last-updated=today
+```
+
+**Example - Skip:**
+```bash
+ace-docs --version      # Trivial, not useful
+ace-docs -h             # Help text, not practical usage
+```
+
+### Architecture Decision Records (ADRs)
+
+For ADR lifecycle management (creation, evolution, archival, scope updates):
+
+**Creating new ADRs:**
+`wfi://docs/create-adr`
+
+**Maintaining existing ADRs:**
+`wfi://docs/maintain-adrs`
+
+ADR maintenance includes:
+- Evolution documentation when patterns change
+- Archival of obsolete decisions
+- Scope updates for partially outdated decisions
+- Synchronization with `docs/decisions.md` summary
+
+### Context Documents (vision.md, architecture.md, etc.)
+
+For core context documents with specific requirements (line limits, update order, duplication prevention), see the specialized workflow:
+
+`wfi://docs/update-context`
+
+This workflow provides:
+- Specific update order to prevent duplication
+- Target line counts for each document
+- Content ownership rules
+- Cross-document validation
+
+## Error Handling
+
+- **Missing frontmatter**: Suggest adding ace-docs frontmatter
+- **Validation failures**: Report specific issues, continue with other docs
+- **Git errors**: Check repository state, suggest fixes
+- **LLM unavailable**: The analyze command will fail - it requires LLM for generating recommendations
+- **Empty analysis**: Check if document has subject configuration and if changes exist in the time period
+
+## Integration Points
+
+### With ace-bundle
+Load project context for documentation:
+```bash
+ace-bundle --preset docs
+```
+
+### With LLM Analysis
+The `ace-docs analyze` command automatically integrates with LLM for intelligent change analysis. The `analysis.md` output provides:
+- Prioritized changes (HIGH/MEDIUM/LOW)
+- Specific recommendations for document updates
+- Context-aware reasoning
+
+No manual LLM integration is needed - it's built into the analyze command.
+
+### With git workflow
+After updates, commit changes:
+```bash
+git add [updated-files]
+git commit -m "docs: Update documentation via ace-docs
+
+- Updated [list of documents]
+- Synchronized with recent changes
+- Validated against configured rules"
+```
+
+## Configuration
+
+### Document Discovery
+Configure in `.ace/docs/config.yml`:
+```yaml
+document_types:
+  guide:
+    paths: ["**/*.g.md", "handbook/guides/**/*.md"]
+    defaults:
+      update_frequency: monthly
+  api:
+    paths: ["*/docs/api/*.md"]
+    defaults:
+      update_frequency: on-change
+```
+
+### Multi-Subject Configuration
+Configure multiple subjects in document frontmatter for categorized analysis:
+```yaml
+ace-docs:
+  subject:
+    - code:
+        diff:
+          paths: ["**/*.rb", "**/*.js"]
+    - config:
+        diff:
+          paths: ["**/*.yml", "**/*.yaml"]
+    - docs:
+        diff:
+          paths: ["**/*.md"]
+```
+
+The `analyze` command will generate separate diffs for each subject, providing more focused analysis.
+
+### Global Rules
+```yaml
+global_rules:
+  max_lines: 1000
+  required_frontmatter: ["doc-type", "purpose"]
+```
+
+## Exit Conditions
+
+Workflow exits when:
+- No documents match selection criteria
+- No changes detected in diff analysis
+- All selected documents processed
+- Critical error prevents continuation
+
+## Usage Examples
+
+### Update specific document (Direct Path)
+```bash
+# When you know exactly which document to update
+# Skip status check and go straight to analysis
+ace-docs analyze ace-docs/README.md
+
+# Review the analysis report
+cat .ace-local/docs/analyze-*/analysis.md
+
+# Update document based on recommendations
+# [Review analysis.md and update content]
+ace-docs update ace-docs/README.md --set last-updated=today
+```
+
+### Update stale guides (Bulk Operation)
+```bash
+# Start with status check for bulk operations
+ace-docs status --type guide --freshness stale
+
+# Analyze changes and generate recommendations
+ace-docs analyze --type guide --freshness stale
+
+# Review the analysis report
+cat .ace-local/docs/analyze-*/analysis.md
+
+# Update each document based on recommendations
+# [Review analysis.md and update content]
+ace-docs update guide1.md --set last-updated=today
+```
+
+### Bulk metadata update
+```bash
+# Update all documents of a type
+ace-docs update --preset standard --set version=2.0
+```
+
+### Pre-commit validation
+```bash
+# Validate all changed documents
+ace-docs validate $(git diff --name-only -- '*.md')
+```
+
+### Analyze and update workflow
+
+#### For specific file (direct):
+```bash
+# Direct analysis when you know the file
+ace-docs analyze docs/architecture.md
+cat .ace-local/docs/analyze-*/analysis.md
+# Review recommendations and update document
+ace-docs update docs/architecture.md --set last-updated=today
+```
+
+#### For bulk updates (status-first):
+```bash
+# Check what needs updating first
+ace-docs status --needs-update
+ace-docs analyze --needs-update
+cat .ace-local/docs/analyze-*/analysis.md
+# Review recommendations and update documents
+ace-docs update [file] --set last-updated=today
+```
+
+## Notes
+
+- The workflow is designed for iterative updates with human/agent oversight
+- Change analysis provides data, but update decisions remain with the operator
+- Metadata-only updates are safe and reversible
+- Content updates should be reviewed before committing

data/lib/ace/docs/atoms/diff_filterer.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Ace
+  module Docs
+    module Atoms
+      # Pure functions for filtering diff content
+      class DiffFilterer
+        class << self
+          # Default patterns to exclude from diffs
+          DEFAULT_EXCLUDE_PATTERNS = [
+            %r{^test/},
+            %r{^spec/},
+            %r{\.test\.},
+            %r{\.spec\.},
+            %r{^coverage/},
+            %r{^tmp/},
+            %r{^vendor/},
+            %r{^node_modules/},
+            %r{^\.git/},
+            %r{Gemfile\.lock$},
+            %r{package-lock\.json$},
+            %r{yarn\.lock$}
+          ].freeze
+
+          # Filter paths from diff output
+          # @param diff [String] The diff content
+          # @param exclude_patterns [Array<Regexp>] Patterns to exclude
+          # @return [String] Filtered diff content
+          def filter_paths(diff, exclude_patterns = DEFAULT_EXCLUDE_PATTERNS)
+            return "" if diff.nil? || diff.empty?
+
+            lines = diff.split("\n")
+            filtered_lines = []
+            skip_until_next_file = false
+
+            lines.each do |line|
+              # Check if this is a file header
+              if file_header?(line)
+                file_path = extract_file_path(line)
+                if should_exclude?(file_path, exclude_patterns)
+                  skip_until_next_file = true
+                else
+                  skip_until_next_file = false
+                  filtered_lines << line
+                end
+              elsif !skip_until_next_file
+                filtered_lines << line
+              end
+            end
+
+            filtered_lines.join("\n")
+          end
+
+          # Estimate the size of a diff in lines
+          # @param diff [String] The diff content
+          # @return [Integer] Number of lines
+          def estimate_size(diff)
+            return 0 if diff.nil? || diff.empty?
+
+            diff.count("\n") + 1
+          end
+
+          # Count significant changes (additions and deletions)
+          # @param diff [String] The diff content
+          # @return [Hash] Statistics about the diff
+          def count_changes(diff)
+            return {additions: 0, deletions: 0, files: 0} if diff.nil? || diff.empty?
+
+            additions = 0
+            deletions = 0
+            files = 0
+
+            diff.split("\n").each do |line|
+              if file_header?(line)
+                files += 1
+              elsif line.start_with?("+") && !line.start_with?("+++")
+                additions += 1
+              elsif line.start_with?("-") && !line.start_with?("---")
+                deletions += 1
+              end
+            end
+
+            {
+              additions: additions,
+              deletions: deletions,
+              files: files,
+              total_changes: additions + deletions
+            }
+          end
+
+          # Check if diff is too large for processing
+          # @param diff [String] The diff content
+          # @param max_lines [Integer] Maximum allowed lines
+          # @return [Boolean] True if diff exceeds limit
+          def exceeds_limit?(diff, max_lines = 100_000)
+            estimate_size(diff) > max_lines
+          end
+
+          private
+
+          # Check if a line is a file header in git diff format
+          def file_header?(line)
+            line.start_with?("diff --git", "+++", "---") ||
+              line.match?(/^index [a-f0-9]+\.\.[a-f0-9]+/)
+          end
+
+          # Extract file path from diff header line
+          def extract_file_path(line)
+            case line
+            when /^diff --git a\/(.+) b\/(.+)$/
+              Regexp.last_match(2) # Use the 'b/' path (new file path)
+            when /^\+\+\+ b\/(.+)$/
+              Regexp.last_match(1)
+            when /^--- a\/(.+)$/
+              Regexp.last_match(1)
+            else
+              ""
+            end
+          end
+
+          # Check if a file path should be excluded
+          def should_exclude?(file_path, patterns)
+            return false if file_path.empty?
+
+            patterns.any? { |pattern| file_path.match?(pattern) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/docs/atoms/frontmatter_free_matcher.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "ace/core/molecules/frontmatter_free_policy"
+
+module Ace
+  module Docs
+    module Atoms
+      # Matches markdown files that are managed without frontmatter.
+      class FrontmatterFreeMatcher
+        def self.match?(path, patterns:, project_root: Dir.pwd)
+          Ace::Core::Molecules::FrontmatterFreePolicy.match?(
+            path,
+            patterns: patterns,
+            project_root: project_root
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ace/docs/atoms/git_date_resolver.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/git_date_resolver"
+
+module Ace
+  module Docs
+    module Atoms
+      # Compatibility shim: delegated to molecule implementation.
+      class GitDateResolver
+        def self.last_updated_for(path)
+          Molecules::GitDateResolver.last_updated_for(path)
+        end
+      end
+    end
+  end
+end

data/lib/ace/docs/atoms/readme_metadata_inferrer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Ace
+  module Docs
+    module Atoms
+      # Infers metadata for README files managed without frontmatter.
+      class ReadmeMetadataInferrer
+        def self.infer(path:, content:, last_updated: nil)
+          return nil unless File.basename(path).casecmp("README.md").zero?
+
+          title = extract_title(content, path)
+          parent = parent_label(path)
+          doc_type = root_readme?(path) ? "root_readme" : "readme"
+          purpose = if doc_type == "root_readme"
+            "Monorepo entry point and navigation for ACE"
+          else
+            "User-facing introduction for #{parent}"
+          end
+
+          metadata = {
+            "doc-type" => doc_type,
+            "purpose" => purpose,
+            "update" => {"frequency" => "on-change"}
+          }
+
+          if last_updated
+            metadata["ace-docs"] = {"last-updated" => last_updated.strftime("%Y-%m-%d")}
+          end
+
+          metadata["title"] = title
+          metadata
+        end
+
+        def self.extract_title(content, path)
+          match = content.to_s.match(/^#\s+([^\n]+)$/)
+          return match[1].strip if match
+
+          parent_label(path)
+        end
+        private_class_method :extract_title
+
+        def self.parent_label(path)
+          parent = File.basename(File.dirname(path.to_s))
+          (parent.nil? || parent.empty? || parent == ".") ? File.basename(Dir.pwd) : parent
+        end
+        private_class_method :parent_label
+
+        def self.root_readme?(path)
+          normalized = path.to_s.sub(%r{\A\./}, "")
+          return true if normalized.casecmp("README.md").zero?
+
+          File.expand_path(path.to_s) == File.join(Dir.pwd, "README.md")
+        rescue
+          false
+        end
+        private_class_method :root_readme?
+      end
+    end
+  end
+end