ace-handbook 0.19.0

data/handbook/guides/quality-assurance/rust.md

@@ -0,0 +1,41 @@
+# Rust Quality Assurance Examples
+
+This file provides Rust-specific examples related to the main [Quality Assurance Guide](../quality-assurance.g.md).
+
+* **Linters/Formatters:** `rustfmt`, `clippy` (run via `cargo fmt` and `cargo clippy`)
+* **Static Analysis:** Rust compiler itself catches many issues; `cargo audit` for security vulnerabilities in dependencies.
+* **Test Coverage:** `cargo-tarpaulin`, `grcov`
+* **CI Configuration:** Examples for GitHub Actions, GitLab CI using Rust toolchain setup actions.
+
+**Example `rustfmt.toml` (Configuration for rustfmt):**
+
+```toml
+# Example rustfmt configuration
+max_width = 100
+use_small_heuristics = "Max"
+# imports_granularity = "Crate"
+```
+
+**Example `clippy.toml` (Configuration for clippy):**
+
+```toml
+# Example clippy configuration
+# Disallow specific lints globally
+disallowed-methods = [
+    # Example: discourage Option::unwrap
+    # "std::option::Option::unwrap",
+]
+
+# Set complexity limits
+cyclomatic-complexity-threshold = 30
+```
+
+**Example CI step for checking formatting and linting:**
+
+```yaml
+- name: Check Formatting
+  run: cargo fmt --all -- --check
+
+- name: Check Lints
+  run: cargo clippy --all-targets -- -D warnings # Fail on warnings
+```

data/handbook/guides/quality-assurance/typescript.md

@@ -0,0 +1,49 @@
+# TypeScript Quality Assurance Examples
+
+This file provides TypeScript-specific examples related to the main [Quality Assurance Guide](../quality-assurance.g.md).
+
+* **Linters/Formatters:** `eslint` (with `@typescript-eslint/parser`), `prettier`
+* **Static Analysis:** TypeScript compiler (`tsc --noEmit`), `sonarjs` (plugin for ESLint)
+* **Test Coverage:** `istanbul` (often via `jest` or `vitest`)
+* **CI Configuration:** Examples for GitHub Actions, GitLab CI using Node.js/TypeScript setup actions.
+
+**Example `.eslintrc.js` (ESLint with TypeScript):**
+
+```javascript
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: [
+    '@typescript-eslint',
+  ],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier', // Make sure prettier is last
+  ],
+  rules: {
+    // Add custom rules here
+  },
+};
+```
+
+**Example Jest config for coverage (`jest.config.js`):**
+
+```javascript
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  collectCoverage: true,
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov'],
+  // Coverage thresholds (optional)
+  // coverageThreshold: {
+  //   global: {
+  //     branches: 80,
+  //     functions: 80,
+  //     lines: 80,
+  //     statements: -10,
+  //   },
+  // },
+};
+```

data/handbook/guides/quality-assurance.g.md

@@ -0,0 +1,222 @@
+---
+doc-type: guide
+title: Quality Assurance Guidelines
+purpose: Documentation for ace-handbook/handbook/guides/quality-assurance.g.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# Quality Assurance Guidelines
+
+## Goal
+
+This guide outlines the processes, tools, and standards used to ensure the quality, reliability, and
+maintainability of the codebase throughout the development lifecycle.
+
+## 1. Code Quality Tools
+
+1. **Static Analysis & Linting Setup**:
+   Configure static analysis and linting tools appropriate for your project's language(s).
+   - Configuration typically involves specifying language versions, enabling/disabling rules, setting formatting
+     preferences, and defining paths to ignore.
+
+   ```yaml
+   # Example conceptual configuration (e.g., for a linter)
+   language_version: "X.Y"
+   fix_on_save: true
+   parallel_processing: true
+   output_format: "progress"
+
+   ignore_paths:
+     - 'bin/*'
+     - 'vendor/**/*'
+     - 'build/*'
+     - 'tmp/*'
+
+   rules:
+     # Specific rule configuration...
+     rule_name: enabled
+   ```
+
+2. **CI Integration**:
+   Integrate static analysis, linting, and code coverage checks into the Continuous Integration
+   (CI) pipeline (e.g., using GitHub Actions, GitLab CI, Jenkins).
+   - Ensure these checks run automatically on pushes and pull requests.
+   - Fail the build if quality checks do not pass.
+
+   ```yaml
+   # Example conceptual CI workflow snippet
+   name: Quality Checks
+
+   on: [push, pull_request]
+
+   jobs:
+     quality:
+       runs-on: ubuntu-latest # Or your preferred runner
+       steps:
+         - uses: actions/checkout@vX # Use appropriate version
+
+         # Add steps for setting up the environment (language, dependencies)
+         # - name: Setup Language Environment
+         #   uses: actions/setup-node@vX # Or setup-ruby, setup-python, etc.
+         # - name: Install Dependencies
+         #   run: your-package-manager install
+
+         - name: Run Linter
+           run: your-linter-command --options # e.g., 
+
+         - name: Run Tests & Coverage
+           run: your-test-runner-command --coverage # e.g., 
+
+         # Optional: Upload coverage reports
+         # - name: Upload Coverage Report
+         #   uses: codecov/codecov-action@vX
+   ```
+
+### 2. Code Review Process
+
+1. **Pull Request Template**:
+
+   ```markdown
+   ## Changes
+   - List key changes
+   - Impact on existing features
+
+   ## Testing
+   - [ ] Unit tests added
+   - [ ] Integration tests updated
+   - [ ] Test coverage maintained
+
+   ## Quality
+   - [ ] Follows coding standards
+   - [ ] Documentation updated
+   - [ ] No new security concerns
+   ```
+
+2. **Review Checklist**:
+
+   ```markdown
+   ### Design
+   - [ ] Follows SDK patterns
+   - [ ] Error handling complete
+   - [ ] Thread safety considered
+
+   ### Implementation
+   - [ ] Clean code principles
+   - [ ] No code smells
+   - [ ] Efficient algorithms
+
+   ### Testing
+   - [ ] Test cases cover edge cases
+   - [ ] Mocks used appropriately
+   - [ ] Performance impacts tested
+   ```
+
+### 3. Test Coverage
+
+1. **Coverage Configuration**:
+   Configure your code coverage tool to:
+   - Exclude test files, vendor directories, and other non-source code paths from the report.
+   - Optionally group coverage results by logical components or modules.
+   - Define minimum coverage thresholds (overall, per-file) to enforce standards. Failing to meet thresholds
+     should ideally fail the build.
+
+   ```javascript
+   // Example conceptual coverage tool setup
+   configureCoverageTool({
+     exclude: [
+       '/tests/',
+       '/specs/',
+       '/vendor/'
+     ],
+     groups: {
+       'Core Logic': 'src/core',
+       'Utilities': 'src/utils',
+       'API Endpoints': 'src/api'
+     },
+     thresholds: {
+       global: {
+         statements: 90,
+         branches: 85,
+         functions: 90,
+         lines: 90
+       },
+       perFile: {
+         statements: 80,
+         lines: 80
+       }
+     }
+   });
+   ```
+
+2. **Coverage Goals**:
+   - Core Components: 95%+ coverage
+   - Tools & Extensions: 90%+ coverage
+   - Integration Points: 85%+ coverage
+
+3. **Coverage Report Example**:
+   (Coverage reports typically show percentage of statements, branches, functions, and lines covered. The exact
+   format varies by tool. File paths will reflect project structure.)
+
+   ```text
+   --------------------------|----------|----------|----------|----------|
+   File                     |  % Stmts |% Branches|  % Funcs |  % Lines |
+   --------------------------|----------|----------|----------|----------|
+   All files                |    92.34 |    89.47 |    91.82 |    92.34 |
+    lib/                    |    100.0 |    100.0 |    100.0 |    100.0 |
+     aira.rb              |    100.0 |    100.0 |    100.0 |    100.0 |
+    lib/aira/             |     91.8 |     88.4 |     90.9 |     91.8 |
+     agent.rb              |     94.3 |     92.1 |     93.7 |     94.3 |
+     tools.rb              |     89.2 |     84.7 |     88.1 |     89.2 |
+   --------------------------|----------|----------|----------|----------|
+   ```
+
+### 4. Continuous Improvement
+
+1. **Code Metrics**:
+   Regularly measure code metrics to identify potential areas for refactoring or improvement.
+   Use tools appropriate for your stack.
+   - **Complexity:** Measure cyclomatic complexity or cognitive complexity using relevant analysis tools.
+   - **Code Size:** Track lines of code (LOC) per module/component using code counting tools.
+   - **TODO/FIXME Notes:** Use tools or scripts to track outstanding `TODO`, `FIXME`, or similar annotations in
+     the codebase.
+
+   ```bash
+   # Example conceptual commands
+   run-complexity-analyzer src/
+   run-lines-of-code-counter src/
+   find-todo-notes src/
+   ```
+
+2. **Quality Monitoring**:
+   - Track code smells over time
+   - Monitor test execution times
+   - Review dependency updates
+
+3. **Technical Debt**:
+
+   ```markdown
+   ## Technical Debt Log
+
+   ### High Priority
+   - [ ] Refactor tool registry for better concurrency
+   - [ ] Improve error context in agent responses
+
+   ### Medium Priority
+   - [ ] Optimize memory usage in large operations
+   - [ ] Enhance logging granularity
+   ```
+
+## Language/Environment-Specific Examples
+
+For specific examples of tool configurations (e.g., linters, static analyzers, coverage tools), CI/CD
+pipeline snippets, or code review checklist details relevant to particular languages or frameworks,
+please refer to the examples in the [./quality-assurance/](./quality-assurance/) sub-directory.
+
+## Related Documentation
+
+- [Coding Standards](./coding-standards.g.md)
+- [Testing Guidelines](guide://testing)
+- [Version Control](./version-control-system.g.md) (PR Templates)
+- [Security](guide://security)

data/handbook/guides/strategic-planning.g.md

@@ -0,0 +1,69 @@
+---
+doc-type: guide
+title: Strategic Planning Guide
+purpose: Documentation for ace-handbook/handbook/guides/strategic-planning.g.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# Strategic Planning Guide
+
+## Purpose
+
+This guide explains **why** and **how** we maintain a living roadmap that aligns day-to-day development with long-term vision.
+
+## 1. Conceptual Model
+
+```text
+Vision → Strategic Objectives → Roadmap (Themes/Epics → Releases) → Tasks
+```
+
+* Vision: enduring North Star.
+* Strategic Objectives: 6–12 m outcomes aligned to vision.
+* Roadmap: rolling plan mapping objectives to concrete Releases.
+* Tasks: granular units executed via workflows.
+
+## 2. Roadmap Document Anatomy
+
+See `/dev-taskflow/roadmap.md`. Key sections:
+
+1. Project Vision
+2. Strategic Objectives (table)
+3. Key Themes & Epics (table)
+4. Planned Major Releases (table)
+5. Cross-Release Dependencies
+6. Update History
+
+## 3. Roadmap Management Lifecycle
+
+1. **Create / Propose Change**: Use `update-roadmap.wf.md` workflow.
+2. **Review**: Stakeholder/lead approves via PR or discussion.
+3. **Update**: Commit changes, increment `last_reviewed` and add entry to *Update History*.
+4. **Quarterly Checkpoint**: At start/end of each release cycle, validate roadmap relevance.
+
+## 4. Roles & Responsibilities
+
+| Role | Responsibilities |
+|------|------------------|
+| Lead Maintainer | Owns roadmap integrity, final approvals |
+| Contributors | Propose updates, align tasks with roadmap |
+| AI Agent | Assist drafting and validating roadmap changes |
+
+## 5. Workflow Integration Points
+
+* **`prepare-tasks.md`**: Must consult roadmap when confirming target releases.
+* **Release Templates**: Reference strategic objectives in release README.
+* **`work-on-task.md`**: Tasks should link back to their roadmap Epic/Theme where applicable.
+
+## 6. Tips & Common Pitfalls
+
+* Avoid overly granular detail in roadmap—keep tactical work in tasks.
+* Review metrics regularly; retire objectives once met.
+* Keep roadmap lightweight—update tables, not essays.
+
+---
+
+## Last Updated
+
+2025-05-07

data/handbook/guides/troubleshooting/ruby.md

@@ -0,0 +1,21 @@
+# Ruby Troubleshooting
+
+Specific tools and techniques for debugging Ruby applications.
+
+## Core tools & tips
+
+* **Read the stack trace first** – top line shows the crash site, lower lines show the call chain.  
+* **Interactive debuggers**  
+  * `binding.pry` for a REPL‑style breakpoint.  
+  * `byebug` (Ruby ≤ 3.0) or `debug` (Ruby ≥ 3.1) for GDB‑like stepping, breakpoints, watch expressions.  
+* **Rails specifics**  
+  * Tune log levels (`config.log_level`) and stream to STDOUT when needed.  
+  * Use view helpers (`debug`, `inspect`) to dump vars in templates during UI bugs.  
+* **Memory leaks** – Valgrind & gems like `memory_profiler`, `derailed_benchmarks`.
+
+## Quick diagnostic checklist
+
+1. Re‑run failing test with `--backtrace` for full context.  
+2. Drop `binding.pry` at suspect line, inspect locals, call `ls` to list methods.  
+3. If timing‑related, add `Rails.logger.debug` statements and compare dev vs prod logs.  
+4. For gem/environment discrepancies, reproduce in a pristine `bundle exec` shell.

data/handbook/guides/troubleshooting/rust.md

@@ -0,0 +1,20 @@
+# Rust Troubleshooting
+
+Specific tools and techniques for debugging Rust applications.
+
+## Core tools & tips
+
+* **Turn on backtraces**: `RUST_BACKTRACE=1 cargo run` prints a full panic trace.  
+* **Native debuggers**  
+  * `rust-gdb` for GNU Debugger workflow with Rust pretty‑printers.  
+  * `rust-lldb` (LLVM) for macOS or LLDB fans.  
+* **IDE integration** – VS Code `code-lldb` or CLion give graphical breakpoints & variable views.  
+* **Build in debug mode** (`cargo build`) to keep symbols; switch to `--release` only after reproducing.  
+* **Common probes**: `dbg!()` macro, `println!("{:?}", var)`; run unit tests with `cargo test -- --nocapture`.
+
+## Quick diagnostic checklist
+
+1. Run failing binary with `RUST_BACKTRACE=full`.  
+2. In LLDB: `break set -n function_name`, `run`, `frame variable`, `next`.  
+3. Suspect UB? Compile with address sanitizer (`-Zsanitizer=address`) or use Clippy’s `pedantic` lints.  
+4. Threading issues – `cargo flamegraph` or `tokio-console` for async bottlenecks.

data/handbook/guides/troubleshooting/typescript.md

@@ -0,0 +1,36 @@
+# TypeScript Troubleshooting
+
+Specific tools and techniques for debugging TypeScript applications, covering both server-side (Node/Deno) and
+client-side (browser) scenarios.
+
+## Server‑side (Node / Deno)
+
+* **Node inspector** – `node --inspect` (or `node --inspect --require ts-node/register app.ts`) opens Chrome
+  DevTools or lets VS Code attach.  
+* **VS Code launch config** example:  
+
+  ```jsonc
+  {
+    "type": "node",
+    "program": "${workspaceFolder}/src/app.ts",
+    "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+  }
+  ```  
+
+* **Auto‑attach** in VS Code terminal for ad‑hoc scripts.  
+* **Security reminder** – never expose the inspector on public interfaces in production.
+
+## Client‑side (browser)
+
+* **Always emit source maps** – `tsc --sourceMap` or `"sourceMap": true` in *tsconfig.json*.  
+* **Chrome/Edge DevTools** display authored TypeScript when maps are present.  
+* **VS Code** offers built‑in Chrome/Edge debug launchers for static HTML or `vite/webpack` dev servers.  
+* **Typical flow** – set breakpoint in `.ts`, refresh page; DevTools pauses on TS line, step, inspect variables.
+
+## Quick diagnostic checklist
+
+1. Confirm maps load (`chrome://inspect` → “Authored” section shows *.ts*).  
+2. For Node, if breakpoints never hit, check `outDir` vs `outFiles` glob mismatch.  
+3. Watch out for "Cannot launch program because corresponding JavaScript cannot be found" – usually missing
+   `sourceMap`.  
+4. Deno: `deno run --inspect-brk main.ts` and attach DevTools or VS Code.