ace-review 0.49.0 → 0.51.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b82396dc00ae89da402caac13c3676fcd153b08cb57d3b7a90ad89741f9dcc35
-  data.tar.gz: f41220f9de17f6a441284da8faa2b5bdeeda271914b1ad50fc4c04bec746958d
+  metadata.gz: 668a87bf537497e9b355bdd43874f45616fa7f07fd1fe7ebbf1c03479d57db73
+  data.tar.gz: c33804be4e90e6d806f383da65dc550eaffbca014ad153994203ca4375f9a4a9
 SHA512:
-  metadata.gz: d67f62b415608b416992a9370d9e2f7bcc275ddb15364327c792f7796cc90497f1c76e63c31da50ef93f806879cc7c539182ebefd392eab1c4c1da1d25b5c96e
-  data.tar.gz: 77225d85b87a7f03f2edff892768a09682f6e4928e76350b5fee7a13a2128e108abd12ad18e333ce9196f807d98f71bafe18b533f6d08a2e036d4537a2a89fa5
+  metadata.gz: 63851c725b131594c27d4b5edd8b9596d2a0f5461ec3976ddda3118169493ec2f6ee2af5e4b7099761e35375ef4e5b8e0047dbb57380c637a6d1c986cee2a606
+  data.tar.gz: 9fb857c6a77358fb8efc4aba526f8af6e7ad7d64a2db6b6ef8be5521bbd5074d4ff9075ecd77ae6112d9bf07c0d6b1b308b0c1315bac08c6291d7e07c33a88c2

data/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.51.0] - 2026-03-28
+
+### Added
+
+- Standardized package review output handling in `review/package` to persist full markdown reports in `.ace-local/review/package/`, with optional `ace-idea` creation for report attachment flow.
+
+## [0.50.3] - 2026-03-28
+
+### Fixed
+- Corrected non-runnable `ace-search` examples in `review/package` for hyphen-prefixed flag discovery and help-text checks.
+- Updated maintainability lint examples to target Ruby implementation files (`$1/lib/**/*.rb`) instead of unsupported directory-only lint targets.
+
+### Changed
+- Standardized quick-reference `ace-search` snippets to match executable command forms used in the workflow body.
+- Clarified that Step 1 shell blocks are reference execution snippets, reduced duplicated evidence-collection instructions, and narrowed D2 usage-doc scanning to `docs/usage.md` when available (with fallback to `docs/`).
+
+## [0.50.2] - 2026-03-28
+
+### Fixed
+- Replaced unsupported glob-style `ace-search` file inventory examples in `review/package` with path-scoped commands that execute correctly.
+- Corrected the I5 help-text evidence command to search a real package path instead of a glob-resolved commands path.
+
+### Changed
+- Made Step 1 package input checks fail-fast (with explicit stop behavior) to prevent downstream review execution on invalid targets.
+- Reworked maintainability checks to reduce duplicate lint noise and clarified that duplication scans are heuristic signals requiring manual confirmation.
+
+## [0.50.1] - 2026-03-28
+
+### Fixed
+- Corrected `review/package` workflow command examples to avoid invalid `ace-bundle` preset usage and path-incompatible `ace-search` patterns.
+- Added argument terminators for hyphen-prefixed search patterns and tightened performance/doc-drift checks to reduce noisy or ambiguous output.
+
+### Changed
+- Aligned package review workflow to executable `ace-*` command surfaces and simplified maintainability checks to use deterministic lint/search evidence.
+
+## [0.50.0] - 2026-03-28
+
+### Changed
+- Expanded `review/package` workflow from placeholder instructions to a comprehensive evidence-first package review protocol spanning maintainability, interface quality, and documentation fidelity checks with required reporting templates.
+
 ## [0.49.0] - 2026-03-24
 
 ### Fixed

data/README.md

@@ -3,7 +3,7 @@
 
   Multi-model code review with preset-based analysis for PRs, tasks, and packages.
 
-  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
   <br><br>
 
   <a href="https://rubygems.org/gems/ace-review"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-review.svg" /></a>

data/handbook/skills/as-review-package/SKILL.md

@@ -6,16 +6,17 @@ description: Review Package - Comprehensive code, docs, UX/DX review with recomm
 # agent: Explore
 user-invocable: true
 allowed-tools:
-  - Bash(ace-bundle:*)
-  - Bash(ace-git:*)
-  - Bash(gh:*)
-  - Read
-  - Glob
-  - Grep
-  - Write
-  - Edit
-  - TodoWrite
-  - Skill
+- Bash(ace-bundle:*)
+- Bash(ace-git:*)
+- Bash(gh:*)
+- Bash(ace-idea:*)
+- Read
+- Glob
+- Grep
+- Write
+- Edit
+- TodoWrite
+- Skill
 argument-hint: [package-name]
 last_modified: 2026-01-10
 source: ace-review

data/handbook/workflow-instructions/review/package.wf.md

@@ -1,16 +1,480 @@
 ---
 doc-type: workflow
+name: review-package
+description: Structured package review workflow with deterministic evidence checks and prioritized findings output
+allowed-tools:
+  - Bash(ace-bundle:*)
+  - Bash(ace-search:*)
+  - Bash(ace-lint:*)
+  - Bash(ace-idea:*)
 title: Review Package Workflow
-purpose: package review workflow
+purpose: Run evidence-first package reviews across maintainability, interface quality, and documentation fidelity
 ace-docs:
-  last-updated: 2026-03-12
-  last-checked: 2026-03-21
+  last-updated: 2026-03-28
+  last-checked: 2026-03-28
 ---
 
 # Review Package Workflow
 
+## Goal
+
+Review a package with a repeatable, evidence-first process that combines deterministic checks and agent judgment, then output prioritized findings and concrete recommendations.
+
+## Arguments
+
+- `$1`: Package name (required), for example `ace-review`
+
+## Prerequisites
+
+- Target package directory exists in repository root
+- `ace-bundle` and `ace-search` available
+- `ace-idea` is optional for persisting the full report as an idea attachment
+
+
+## Priority Model
+
+Use these severity markers in findings:
+
+- `🔴 Immediate`: must address now (correctness, security, severe maintainability risk)
+- `🟡 Next Release`: should address in the next release cycle
+- `🟢 Backlog`: useful improvements with lower urgency
+- `🔵 Advisory`: informational guidance
+
+## Findings Tables
+
+Per-finding table:
+
+```markdown
+| # | Dimension | Check | Priority | Evidence | File(s) | Recommendation | Tool |
+|---|-----------|-------|----------|----------|---------|----------------|------|
+```
+
+Summary counts table:
+
+```markdown
+| Dimension | Immediate | Next Release | Backlog | Advisory | Total |
+|-----------|-----------|--------------|---------|----------|-------|
+```
+
 ## Instructions
 
-1. Load package context with `ace-bundle <package-name>/project` when available.
-2. Review library structure, public CLI/API surface, documentation, and tests.
-3. Produce prioritized findings and concrete follow-up recommendations.
+### Step 1: Validate Package Input
+
+1. Ensure package argument is present:
+   These shell blocks are reference command snippets for agent execution flow checks; they are not intended to be run as a standalone script.
+
+```bash
+if [ -z "$1" ]; then
+  echo "Usage: /as-review-package <package-name>"
+  ace-search "^ace-" "." --files
+  exit 1
+fi
+```
+
+2. Ensure target path exists:
+
+```bash
+if [ ! -d "$1" ]; then
+  echo "Package not found: $1"
+  ace-search "^ace-" "." --files
+  exit 1
+fi
+```
+
+3. If missing, list candidate packages and stop:
+
+```bash
+ace-search "^ace-" "." --files
+```
+
+### Step 2: Load Review Context
+
+1. Load baseline project context:
+
+```bash
+ace-bundle project
+```
+
+2. Gather package-specific context directly:
+
+```bash
+ace-search "." "$1" --files
+```
+
+3. Continue with project context and direct package inspection.
+
+4. Initialize deterministic report output target:
+
+```bash
+package_slug="$(printf '%s' "$1" | tr '/ ' '-')"
+review_timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
+report_dir=".ace-local/review/package/${package_slug}"
+report_path="${report_dir}/raw-review-${review_timestamp}.md"
+mkdir -p "$report_dir"
+```
+
+### Step 3: Build Evidence Inventory
+
+Collect key files for later cross-checking:
+
+```bash
+# Reuse the file inventory collected in Step 2.
+ace-search "^#|^##|class |module |desc " "$1" --content
+```
+
+Minimum evidence set:
+
+- `README.md` and package `docs/usage.md` (if present)
+- `CHANGELOG.md`
+- `exe/*` and CLI command files
+- `lib/**` implementation files
+- `test/**` test files
+- `.ace-defaults/**` configuration defaults
+- `handbook/**` workflows and guides
+
+### Step 4: Maintainability Review (Deterministic)
+
+Run these checks first. Record evidence and thresholds.
+
+#### M1. Test Coverage Ratio
+
+Goal: test file count to implementation file count at or above `0.8:1`.
+
+```bash
+ace-search "\\.rb$" "$1/lib" --files
+ace-search "_test\\.rb$" "$1/test" --files
+```
+
+Thresholds:
+
+- `🔴`: ratio `< 0.5`
+- `🟡`: ratio `>= 0.5` and `< 0.8`
+- `🟢`: ratio `>= 0.8`
+
+If SimpleCov artifact exists, include coverage percentage as supporting evidence. If absent, note "coverage artifact unavailable".
+
+#### M2. File Size Compliance
+
+Target: identify oversized implementation hotspots with lint + structure evidence.
+
+```bash
+ace-search "\\.rb$" "$1/lib" --files
+ace-lint "$1/lib/**/*.rb"
+```
+
+Thresholds:
+
+- `🔴`: repeated severe lint hotspots in core files (for example excessive method/class complexity with large files)
+- `🟡`: moderate lint hotspots concentrated in a few files
+- `🟢`: no major lint hotspots reported
+
+#### M3. Code Duplication
+
+Heuristic scan (not deterministic):
+
+```bash
+ace-search "def " "$1/lib" --content
+ace-search "TODO: duplicate|duplicate" "$1/lib" --content
+```
+
+Interpretation:
+
+- Treat matches as hints and confirm true duplication by reading candidate methods side-by-side before escalating priority.
+
+#### M4. Complexity Hotspots
+
+Baseline:
+
+```bash
+# Reuse M2 lint output as baseline; rerun only if the file set changed.
+ace-lint "$1/lib/**/*.rb"
+```
+
+#### M5. Code Smells
+
+Evidence scan:
+
+```bash
+ace-search "TODO|FIXME|HACK|XXX|rescue StandardError|puts\\(|binding\\.pry" "$1/lib" --content
+```
+
+Use this check for smell-specific signals; rely on M4's `ace-lint` output for complexity hotspots.
+
+#### M6. ATOM Architecture Compliance
+
+Check expected layering and cross-layer imports.
+
+```bash
+ace-search "atoms" "$1/lib" --files
+ace-search "molecules" "$1/lib" --files
+ace-search "organisms" "$1/lib" --files
+ace-search "require .*organisms" "$1/lib" --content
+```
+
+Flag atom-to-organism or atom-to-cli coupling as maintainability risk.
+
+#### M7. Dead Code and Technical Debt
+
+```bash
+ace-search "TODO|FIXME|HACK|XXX" "$1" --content
+ace-search "deprecated|obsolete|legacy" "$1/lib" --content
+```
+
+Score by density and stale markers without owners.
+
+#### M8. Dependency Hygiene
+
+Compare gemspec dependencies with runtime requires.
+
+```bash
+ace-search "add_dependency|add_runtime_dependency" "$1" --content
+ace-search "^require " "$1/lib" --content
+```
+
+Flag missing or unused dependencies and hidden runtime dependencies.
+
+#### M9. Changelog Maintenance
+
+```bash
+[ -f "$1/CHANGELOG.md" ] && ace-search "^## \[" "$1" --content || echo "CHANGELOG.md not found"
+[ -f "$1/CHANGELOG.md" ] && ace-search "Added|Changed|Fixed|Security" "$1" --content || echo "CHANGELOG.md not found"
+```
+
+Check format consistency and recency relative to recent commits.
+
+### Step 5: Interface Quality Review (Evidence Then Judgment)
+
+Gather evidence first, then evaluate.
+
+#### I1. CLI Flag Consistency
+
+```bash
+ace-search "option .*aliases:" "$1/lib" --content
+ace-search "(-v|-q|-d|-h|--help)" "$1/lib" --content
+```
+
+Evaluate reserved-flag usage and naming consistency.
+
+#### I2. Error Message Quality
+
+```bash
+ace-search "raise|error|fail" "$1/lib" --content
+```
+
+Check messages for actionability and recovery guidance.
+
+#### I3. Exit Code Documentation
+
+```bash
+ace-search "exit code|Exit codes|status code" "$1" --content
+ace-search "Ace::Core::CLI::Error|exit" "$1/lib" --content
+```
+
+Evaluate documentation-to-implementation alignment.
+
+#### I4. API Surface Consistency
+
+```bash
+ace-search "module Ace::|class .*Command" "$1/lib" --content
+ace-search "public|private" "$1/lib" --content
+```
+
+Assess naming cohesion and public API boundaries.
+
+#### I5. Help Text Quality
+
+```bash
+ace-search "desc \"|argument :|option :" "$1/lib" --content
+```
+
+Evaluate completeness, examples, and clarity.
+
+#### I6. Extensibility
+
+```bash
+ace-search "hook|plugin|adapter|strategy|provider" "$1/lib" --content
+```
+
+Evaluate extension points and coupling tradeoffs.
+
+#### I7. Performance Characteristics
+
+```bash
+ace-search "File\\.read|IO\\.read|YAML\\.load|JSON\\.parse|each_slice|each_cons|nested loop|while .*each" "$1/lib" --content
+```
+
+Assess patterns for large inputs (streaming vs full load) and potential hotspots.
+
+### Step 6: Documentation Fidelity Review
+
+Cross-check docs against implementation behavior.
+
+#### D1. README Accuracy
+
+```bash
+ace-search "ace-" "$1" --content
+ace-search "desc \"" "$1/lib" --content
+```
+
+Compare documented commands/flags with actual CLI definitions.
+
+#### D2. Usage Docs Drift
+
+```bash
+[ -f "$1/docs/usage.md" ] && ace-search "usage|example|command|option" "$1/docs/usage.md" --content || ([ -d "$1/docs" ] && ace-search "usage|example|command|option" "$1/docs" --content || echo "docs/ directory not found")
+ace-search "class .*Command|desc \"|option :" "$1/lib" --content
+```
+
+If `docs/usage.md` is missing, note as advisory unless required by package conventions. The docs search above intentionally gathers usage context from `docs/` when present.
+
+#### D3. CHANGELOG Completeness
+
+```bash
+[ -f "$1/CHANGELOG.md" ] && ace-search "^## \[" "$1" --content || echo "CHANGELOG.md not found"
+```
+
+Check whether notable changes appear in changelog entries.
+
+#### D4. Help Text Accuracy
+
+```bash
+ace-search "(--help|-h)" "$1" --content
+```
+
+Compare docs to command definitions and expected help output.
+
+#### D5. Config Documentation Fidelity
+
+```bash
+ace-search "\.ace-defaults|config.yml|resolve_namespace" "$1" --content
+ace-search "config|\.ace/" "$1" --content
+```
+
+Cross-check config keys and precedence explanations.
+
+#### D6. ADR and Standards Alignment
+
+```bash
+ace-search "ADR-|ATOM|workflow|ace-bundle" "$1" --content
+```
+
+Verify references point to real practices and files.
+
+### Step 7: Handle Optional Tool Availability
+
+If optional tooling is not installed:
+
+1. Record the tool as unavailable.
+2. Record fallback command(s) used.
+3. Continue review without failing the workflow.
+4. Add advisory recommendation with install guidance where useful.
+
+### Step 8: Compile Findings
+
+1. Build one findings row per issue using the required columns:
+
+- `Dimension`: Maintainability, Interface Quality, or Documentation Fidelity
+- `Check`: check id/name (for example `M4 Complexity Hotspots`)
+- `Priority`: one of `🔴/🟡/🟢/🔵`
+- `Evidence`: concrete command result summary
+- `File(s)`: exact file paths
+- `Recommendation`: action with scope
+- `Tool`: command/tool used (or fallback)
+
+2. Produce summary count table by dimension and priority.
+
+### Step 9: Prioritize Recommendations
+
+Group actions into buckets:
+
+1. `Immediate`: correctness/security/severe quality risks
+2. `Next Release`: high-value improvements with moderate risk
+3. `Backlog`: incremental maintainability improvements
+4. `Advisory`: non-blocking guidance
+
+Add rough effort tags where possible (`S`, `M`, `L`).
+
+### Step 10: Final Review Output and Report Artifact
+
+Your final package review output should contain, in order:
+
+1. Scope and package reviewed
+2. Tool availability notes
+3. Findings table
+4. Summary table
+5. Prioritized recommendation list
+6. Brief closing note with follow-up suggestion
+
+Use the same content to create a full markdown report file:
+
+```bash
+cat <<EOF > "$report_path"
+# Package Review Report: $1
+
+Scope and package reviewed: $1
+
+## Tool Availability
+
+## Findings
+
+| # | Dimension | Check | Priority | Evidence | File(s) | Recommendation | Tool |
+|---|-----------|-------|----------|----------|---------|----------------|------|
+
+## Summary
+
+| Dimension | Immediate | Next Release | Backlog | Advisory | Total |
+|-----------|-----------|--------------|---------|----------|-------|
+
+## Prioritized Recommendations
+
+## Closing Note
+EOF
+
+echo "Full report saved to: $report_path"
+
+if command -v ace-idea >/dev/null 2>&1; then
+  ace-idea create "Package review report for ${1}. Full report is attached as full-report.md in the idea folder." --title "Review package ${1}" --tags review,package --move-to maybe
+  echo "Use the output Path above to attach report artifact:"
+  echo "Set idea_file_path to the \"Path:\" value above and run:"
+  echo "cp \"$report_path\" \"\$(dirname \"$idea_file_path\")/full-report.md\""
+else
+  echo "ace-idea not available; full report available at: $report_path"
+fi
+```
+
+## Error Handling
+
+- Package not found: show clear error and available package list
+- Package-specific bundle unavailable: continue with project bundle and direct inspection
+- Optional tool missing: continue with fallback and document limitation
+- Coverage artifact unavailable: report coverage metric as unavailable (do not block)
+
+## Quick Reference
+
+```bash
+# Load context
+ace-bundle project
+ace-search "\\.rb$" "<package>/lib" --files
+
+# Core evidence scans
+ace-search "<pattern>" <package> --content
+ace-search "\\.rb$" <package> --files
+
+# Protocol load check for this workflow
+ace-bundle wfi://review/package
+
+# Lint this workflow file
+ace-lint ace-review/handbook/workflow-instructions/review/package.wf.md
+```
+
+## Success Criteria
+
+- [ ] `package.wf.md` is expanded from placeholder instructions to a comprehensive workflow
+- [ ] Maintainability section defines 9 deterministic checks with thresholds or clear fallbacks
+- [ ] Interface Quality section defines 7 evidence-first checks
+- [ ] Documentation Fidelity section defines 6 doc-vs-code cross-checks
+- [ ] Findings output includes required per-finding table format
+- [ ] Summary output includes required dimension/priority counts table
+- [ ] Missing optional tools are handled as non-blocking with explicit notes
+- [ ] Workflow loads with `ace-bundle wfi://review/package`
+- [ ] File passes `ace-lint`

data/lib/ace/review/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Review
-    VERSION = "0.49.0"
+    VERSION = "0.51.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ace-review
 version: !ruby/object:Gem::Version
-  version: 0.49.0
+  version: 0.51.0
 platform: ruby
 authors:
 - Michal Czyz