ace-docs 0.31.0

data/handbook/workflow-instructions/docs/squash-changelog.wf.md

@@ -0,0 +1,246 @@
+---
+doc-type: workflow
+title: Squash Changelog Entries Workflow
+purpose: changelog management workflow instruction
+ace-docs:
+  last-updated: 2026-02-22
+  last-checked: 2026-03-21
+---
+
+# Squash Changelog Entries Workflow
+
+Consolidate multiple CHANGELOG.md version entries added on a feature branch into a single entry before merging to the target branch.
+
+## When to Use
+
+On feature branches with multiple `ace-release` cycles that each added a version entry to root `CHANGELOG.md`. Before merging the PR, squash these into one entry using the **lowest** version number.
+
+## Prerequisites
+
+- On a feature branch (not main/master)
+- Root `CHANGELOG.md` exists with entries added during this branch's lifecycle
+- Entries follow [Keep a Changelog](https://keepachangelog.com/) format
+
+## Steps
+
+### 1. Safety Check
+
+Verify you are NOT on main/master:
+
+```bash
+BRANCH=$(git branch --show-current)
+```
+
+If on `main` or `master`, **STOP** unless `--force` was passed. Squashing on main would alter published history.
+
+### 2. Determine Target Branch
+
+Use this priority order to find the branch this PR targets:
+
+1. **Embedded context** — check `<current_repository_status>` for "Current PR → Target: X"
+2. **Explicit argument** — if user passed a branch name, use it
+3. **GitHub CLI** — `gh pr view --json baseRefName --jq '.baseRefName'`
+4. **Fallback** — `main`
+
+```bash
+TARGET=$(gh pr view --json baseRefName --jq '.baseRefName' 2>/dev/null || echo main)
+```
+
+### 3. Detect New Entries
+
+Use the embedded `<changelog_diff>` section if available. Otherwise:
+
+```bash
+git diff "$TARGET" -- CHANGELOG.md
+```
+
+Extract all new `## [X.Y.Z]` version headers that were **added** (lines starting with `+## [`).
+
+```bash
+git diff "$TARGET" -- CHANGELOG.md | grep -E '^\+## \[[0-9]+\.[0-9]+\.[0-9]+\]' | sed 's/^\+//'
+```
+
+### 4. Validate Entry Count
+
+| Count | Action |
+|-------|--------|
+| 0 | Report "No new changelog entries found — nothing to squash." **STOP.** |
+| 1 | Report "Only one entry found — already consolidated, nothing to squash." **STOP.** |
+| 2+ | Proceed to squash. |
+
+### 5. Parse Entries
+
+Read `CHANGELOG.md` and extract each new entry's content:
+
+- For each detected version header, capture everything from `## [X.Y.Z]` down to (but not including) the next `## [` header
+- Parse into categories: Fixed, Added, Removed, Changed, Technical
+- Preserve individual line items with their package version prefixes (e.g., `**ace-foo v1.2.3**:`)
+
+### 6. Select Version
+
+Use the **LOWEST** version number from the detected entries (numeric comparison, not lexicographic).
+
+**Numeric comparison**: Compare major, then minor, then patch as integers.
+- `0.9.496` < `0.9.497` < `0.9.498` → select `0.9.496`
+
+Keep the **date** from the lowest version entry (it was the first release on this branch).
+
+### 7. Merge Categories
+
+Combine all items across entries by category, following this canonical order:
+
+1. **Fixed**
+2. **Added**
+3. **Removed**
+4. **Changed**
+5. **Technical**
+
+Rules:
+- **Dedup similar items**: If two entries describe the same fix/feature with slightly different wording, keep the more descriptive one
+- **Preserve package prefixes**: Keep `**ace-foo vX.Y.Z**:` prefixes for traceability
+- **Skip empty categories**: Only include categories that have items after merging
+- **Within each category**: Order items by package name, then by version (ascending)
+
+### 8. Preview
+
+Show the squashed entry to the user. Format:
+
+```
+--- Squashed changelog entry ---
+Merging N entries ([highest]...[lowest]) into single [lowest] entry:
+
+## [X.Y.Z] - YYYY-MM-DD
+
+### Fixed
+- item 1
+- item 2
+
+### Added
+- item 3
+
+...
+--- End preview ---
+
+Confirm: Replace N entries with this single entry? (Y/n)
+```
+
+Wait for user confirmation before proceeding.
+
+### 9. Replace
+
+Use the **Edit** tool to replace the multi-entry block in `CHANGELOG.md`:
+
+- `old_string`: The entire block from the first (highest version) `## [X.Y.Z]` header through the last line of the last (lowest version) entry, up to but not including the next pre-existing `## [` header
+- `new_string`: The single squashed entry from step 8
+
+### 10. Verify
+
+After replacement, confirm correctness:
+
+```bash
+# Old versions should be gone
+grep -E "## \[OLD_VERSION\]" CHANGELOG.md
+# Should return no results for removed versions
+
+# New version should be present
+grep -E "## \[LOWEST_VERSION\]" CHANGELOG.md
+# Should return exactly one match
+
+# Unreleased section should be intact
+grep "## \[Unreleased\]" CHANGELOG.md
+# Should return one match
+```
+
+### 11. Report
+
+Print a summary:
+
+```
+Squashed N changelog entries into one:
+  Removed: [0.9.498], [0.9.497]
+  Kept:    [0.9.496] (with all 13 items merged)
+
+Changes are NOT committed. Review and commit when ready.
+```
+
+## Edge Cases
+
+### Different Dates Across Entries
+
+Use the date from the **lowest** version (earliest release on this branch). The squashed entry represents the cumulative work starting from that point.
+
+### Multiple Packages in Same Category
+
+Keep all items — each has its own package prefix for disambiguation:
+
+```markdown
+### Fixed
+- **ace-assign v0.7.3**: Fix A
+- **ace-assign v0.7.5**: Fix B
+```
+
+### Dirty Working Tree
+
+If there are uncommitted changes to `CHANGELOG.md`, warn the user:
+
+```
+Warning: CHANGELOG.md has uncommitted changes. These will be included in the squash result.
+Proceed anyway? (y/N)
+```
+
+### Version Comparison
+
+Always compare versions **numerically**, not as strings:
+- `0.9.10` > `0.9.9` (numeric: 10 > 9)
+- String comparison would incorrectly say `0.9.9` > `0.9.10`
+
+Split on `.`, compare each segment as integers.
+
+## Examples
+
+### Example 1: Three Entries on Feature Branch
+
+Before:
+```markdown
+## [Unreleased]
+
+## [0.9.498] - 2026-02-13
+### Fixed
+- **ace-assign v0.7.5**: Fix A
+### Changed
+- **ace-assign v0.7.5**: Change B
+
+## [0.9.497] - 2026-02-13
+### Fixed
+- **ace-assign v0.7.4**: Fix C
+### Added
+- **ace-assign v0.7.4**: Feature D
+
+## [0.9.496] - 2026-02-13
+### Added
+- **ace-assign v0.7.3**: Feature E
+### Fixed
+- **ace-assign v0.7.3**: Fix F
+```
+
+After squash:
+```markdown
+## [Unreleased]
+
+## [0.9.496] - 2026-02-13
+### Fixed
+- **ace-assign v0.7.3**: Fix F
+- **ace-assign v0.7.4**: Fix C
+- **ace-assign v0.7.5**: Fix A
+### Added
+- **ace-assign v0.7.3**: Feature E
+- **ace-assign v0.7.4**: Feature D
+### Changed
+- **ace-assign v0.7.5**: Change B
+```
+
+### Example 2: Already Squashed
+
+```
+Only one entry found ([0.9.496]) — already consolidated, nothing to squash.
+```

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

@@ -0,0 +1,361 @@
+---
+doc-type: workflow
+title: Update Project Blueprint Workflow Instruction
+purpose: Documentation for ace-docs/handbook/workflow-instructions/docs/update-blueprint.wf.md
+ace-docs:
+  last-updated: 2026-02-23
+  last-checked: 2026-03-21
+---
+
+# Update Project Blueprint Workflow Instruction
+
+## Goal
+
+Update the `docs/blueprint.md` file with a concise summary of the current project structure, key files, and links to
+core project documents. The blueprint provides essential orientation for developers and AI agents to quickly understand
+the project organization.
+
+## Definition
+
+A "blueprint" in this context is a concise overview document that provides orientation to the project's structure and
+organization, highlighting key directories and files to help developers (especially AI assistants) quickly understand
+how to navigate the codebase.
+
+## Prerequisites
+
+* Project structure should be relatively stable
+* Core documents (`vision.md`, `architecture.md`) should exist and be reasonably up-to-date
+* Write access to `dev-taskflow/` directory
+
+## Project Context Loading
+
+* Read and follow: `ace-bundle wfi://bundle`
+
+## High-Level Execution Plan
+
+### Planning Phase
+
+* Analyze current project structure
+* Identify key directories and files
+* Check for existing specialized
+  documentation (tools.md, etc.)
+* Determine what has changed since last
+  update
+
+
+### Execution Phase
+
+* Generate updated directory structure
+  overview
+* Update key file descriptions
+* Verify and update document links
+* Add read-only and ignored paths sections
+* Save updated blueprint
+
+
+## Process Steps
+
+1.  **Identify Core Project Documents:**
+    * Verify `docs/vision.md` and `docs/architecture.md` are present
+    * Check for any additional core documentation files
+2.  **Generate Blueprint Structure:**
+    
+    Use the blueprint template:
+
+3.  **Analyze Project Structure:**
+    * Use enhanced tree navigation to get current structure:
+      
+          nav-tree --project-structure --filter source
+      {: .language-bash}
+    
+    * Identify main source directories with enhanced navigation: nav-ls --long src/ app/ lib/
+      {: .language-bash}
+    
+    * Note test directory location and submodules with context awareness
+    * Document any submodules if present
+4.  **Update Directory Descriptions:**
+    * Replace placeholder directories with actual project structure
+    * Add brief descriptions for each major directory
+    * Include relationship between directories if relevant
+5.  **Identify Key Project-Specific Files:**
+    * List critical configuration files
+    * Include entry points and main modules
+    * Focus on files unique to this project
+    * Add version/build files (package.json, Gemfile, etc.)
+    * **For tools**: If `docs/tools.md` exists, reference it instead of duplicating tool lists
+6.  **Extract Technology Stack:**
+    * Read from architecture.md or analyze project files
+    * Identify primary language and version
+    * List main framework and key libraries
+    * Include database and external services
+7.  **Define Agent Guidelines:**
+    * Specify read-only paths (archived releases, etc.)
+    * List ignored paths (dependencies, logs, etc.)
+    * Add project-specific restrictions
+8.  **Update Links and Save:**
+    * Ensure all internal document links are correct
+    * Verify file paths are relative to blueprint location
+    * Save the updated `docs/blueprint.md` file
+
+## Common Directory Patterns
+
+### Web Applications
+
+    app/          # Application code
+    config/       # Configuration files
+    public/       # Static assets
+    views/        # Templates
+
+### Libraries/Packages
+
+    lib/          # Library source code
+    examples/     # Usage examples
+    benchmarks/   # Performance tests
+
+### Microservices
+
+    services/     # Individual services
+    shared/       # Shared code
+    infra/        # Infrastructure config
+
+## Technology Stack Detection
+
+### Node.js
+
+* Look for: `package.json`, `node_modules/`
+* Key files: `index.js`, `server.js`, `app.js`
+
+### Ruby
+
+* Look for: `Gemfile`, `Rakefile`, `.ruby-version`
+* Key files: `config.ru`, `app.rb`
+
+### Python
+
+* Look for: `requirements.txt`, `setup.py`, `pyproject.toml`
+* Key files: `__main__.py`, `app.py`, `main.py`
+
+### Rust
+
+* Look for: `Cargo.toml`, `Cargo.lock`
+* Key files: `main.rs`, `lib.rs`
+
+## Output / Success Criteria
+
+* `docs/blueprint.md` file is created or updated
+* Contains accurate directory structure representation
+* Technology stack is correctly identified
+* Key files are listed with descriptions
+* Read-only and ignored paths are specified
+* All document links are valid and relative
+* Information complements (not duplicates) other docs
+* Tools information references `docs/tools.md` if it exists rather than duplicating
+
+## Usage Example
+
+Invoke this workflow when:
+
+* Significant structural changes have occurred
+* Before starting a major planning phase
+* When onboarding new team members or AI agents
+* After major refactoring or reorganization
+
+Example:
+
+> "Update the blueprint to reflect our new microservices structure"
+
+## Best Practices
+
+**DO:**
+
+* Keep descriptions concise and focused
+* Update after major structural changes
+* Include technology versions when known
+* Specify AI agent guidelines clearly
+* Use relative paths for all links
+
+**DON'T:**
+
+* Include temporary or generated files
+* Duplicate architecture documentation
+* Duplicate detailed tools information (if `docs/tools.md` exists, reference it instead)
+* List every single file
+* Include sensitive information
+* Use absolute file paths
+
+<documents>
+    <template name="blueprint" markdown="1"># Project Blueprint: [Project Name]
+
+## What is a Blueprint?
+
+This document provides a concise overview of the project's structure and organization, highlighting key directories and files to help developers (especially AI assistants) quickly understand how to navigate the codebase. It should be updated periodically using the `update-blueprint` workflow.
+
+## Core Project Documents
+
+- [What We Build](docs/vision.md) - Project vision and goals
+- [Architecture](docs/architecture.md) - System design and implementation principles
+- [Blueprint](docs/blueprint.md) - Project structure and organization
+
+## Project Organization
+
+<!-- Describe your project's main directory structure -->
+
+
+
+This project follows a documentation-first approach with these primary directories:
+
+- **docs/** - Project documentation
+  - **guides/** - Best practices and development standards
+  - **architecture/** - System design and decisions
+  - **workflow-instructions/** - Structured commands for AI agents
+  - **zed/** - Editor integration (if applicable)
+
+- **dev-taskflow/** - Project-specific documentation
+  - **current/** - Active release cycle work
+  - **backlog/** - Pending tasks for future releases
+  - **done/** - Completed releases and tasks
+  - **decisions/** - Architecture Decision Records (ADRs)
+
+- **bin/** - Executable scripts for project management and automation
+
+- **src/** - Source code (adjust directory names as needed)
+  - **[component1]/** - Core functionality
+  - **[component2]/** - Additional features
+  - **utils/** - Shared utilities
+
+- **tests/** - Test files and test utilities
+
+- **config/** - Configuration files
+
+<!-- Add your project-specific directories here -->
+
+
+
+## View Complete Directory Structure
+
+To see the complete filtered directory structure, run:
+
+```bash
+nav-tree
+```
+
+This will show all project files while filtering out temporary files, session logs, and other non-essential directories.
+
+## Key Project-Specific Files
+
+<!-- List important files that developers should know about -->
+
+
+
+- [Documentation](docs/README.md) - Project documentation hub
+- [Development Guides](docs/guides/README.md) - Development standards and best practices
+- [Configuration](README.md) - Configuration documentation (if applicable)
+
+## Technology Stack
+
+<!-- Summarize the main technologies used -->
+
+
+
+- **Primary Language**: [e.g., JavaScript, Python, Rust]
+- **Framework**: [e.g., React, Django, Axum]
+- **Database**: [e.g., PostgreSQL, MongoDB, SQLite]
+- **Key Libraries**: [List important dependencies]
+- **Development Tools**: [e.g., Docker, Webpack, Cargo]
+
+## Read-Only Paths
+
+This section lists files and directories that the agent should treat as read-only. Attempts to modify these paths should be flagged or prevented.
+
+<!-- Add project-specific read-only paths -->
+
+
+- `docs/decisions/**/*`
+- `dev-taskflow/done/**/*`
+- `*.lock` # Dependency lock files
+- `dist/**/*` # Built artifacts
+- `build/**/*` # Build output
+
+## Ignored Paths
+
+This section lists files, directories, or glob patterns that the agent should ignore entirely during its operations (e.g., when searching, reading, or editing files).
+
+- `dev-taskflow/done/**/*` # Default: Protects completed tasks and releases
+- `**/node_modules/**`
+- `**/.git/**`
+- `**/__pycache__/**`
+- `**/target/**` # Rust build artifacts
+- `**/dist/**` # Built distributions
+- `**/build/**` # Build artifacts
+- `**/.env` # Environment files
+- `**/.env.*` # Environment variants
+- `*.session.log`
+- `*.lock`
+- `*.tmp`
+- `*~` # Backup files
+- `**/.DS_Store` # macOS system files
+- `**/Thumbs.db` # Windows system files
+
+## Entry Points
+
+<!-- Document the main ways to start or interact with the project -->
+
+
+
+### Development
+
+```bash
+# Start development server
+bin/run
+
+# Run tests
+# Run project-specific test command
+
+# Build for production
+bin/build
+```
+
+### Common Workflows
+
+- **New Feature**: Use `task-manager next` to find next task, follow task workflow
+- **Bug Fix**: Create task in backlog, prioritize, implement
+- **Documentation**: Update relevant files in `dev-taskflow/`
+
+## Dependencies
+
+<!-- List major external dependencies and their purposes -->
+
+
+
+### Runtime Dependencies
+
+- [Library 1]: Purpose and version constraints
+- [Library 2]: Purpose and version constraints
+
+### Development Dependencies
+
+## Submodules
+
+<!-- Document any Git submodules used -->
+
+
+
+### docs-dev (if applicable)
+
+- Path: `docs-dev`
+- Repository: [Repository URL]
+- Purpose: Development workflows and guides
+- **Important**: Commits for this submodule must be made from within the submodule directory
+
+### [Other Submodules]
+
+- Path: `[path]`
+- Repository: [Repository URL]
+- Purpose: [Description]
+
+---
+
+*This blueprint should be updated when significant structural changes are made to the project. Use the `update-blueprint` workflow to keep it current.*
+</template>
+</documents>
+