appydave-tools 0.75.0 → 0.76.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e45ff57b507a705f826281a7d361abf0724d719eaf1c1ba4795198f3a4551a7f
-  data.tar.gz: edfc8fcdb775c290d9c59a588215de3e2c613075ee49332836bf19de92a5126b
+  metadata.gz: 2700178e0f8e7fa1ddbd046cb78af4a0a340f2e8770637a2f3b30229e9f76179
+  data.tar.gz: c5c3f8094e988cc77849f27d1126c3839825d231c06b8bb63d3410cfdfe72179
 SHA512:
-  metadata.gz: d5d45772ed9304ac22cca51417c0d48b0d176d824933feaafbc4a34c50ff8585bbce93a4f423ecadc39ac64aeca5e0e2724556a1407c428a318fa86926a65899
-  data.tar.gz: ab16611805c302aeb6fe1930e3502d4330cb00833bd282e2631e9cbb25f6fc179eb66c7e6cd4535a89005cd743cc0db6c3e9eaaaeea0a22c671274e5b6f9b43d
+  metadata.gz: e11cda4ffd9a0a555c15ae613e94b31aa7f508ba473ccc89d31a48d399f9b603204faa4018bea222f9640205b5d73a557b992acf3be94c926bdbeea494baedb5
+  data.tar.gz: 4af0c479f1aeb82cc32dd06d8d954910fff6e9a4a2f785d2969a284fc9a55874a56ed71e1600be9c26b5ad3792a67be98105a9003b82c8d835eb0bd8a7d323cf

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+# [0.76.0](https://github.com/appydave/appydave-tools/compare/v0.75.0...v0.76.0) (2026-03-19)
+
+
+### Bug Fixes
+
+* fix pre-existing rubocop offenses in bin/dam and split jump test helpers to avoid OneClassPerFile ([491b980](https://github.com/appydave/appydave-tools/commit/491b980c335b7e3d205a5368cd0a7b96e5b5a82f))
+* remove debug puts and fix unguarded FileUtils.cd in FileCollector; close BUG-1 ([13d5f87](https://github.com/appydave/appydave-tools/commit/13d5f8793d5185cb9795cab86a5270726763c30e))
+
+
+### Features
+
+* add AI-friendly help system to GPT Context ([c0b8843](https://github.com/appydave/appydave-tools/commit/c0b884323654a248d660ea137712e7c0e5fc172c))
+
+# [0.75.0](https://github.com/appydave/appydave-tools/compare/v0.74.1...v0.75.0) (2026-02-08)
+
+
+### Bug Fixes
+
+* fix RuboCop violations in jump report commands ([261404e](https://github.com/appydave/appydave-tools/commit/261404ed5cc9e3b93c64db30548728992b353355))
+
+
+### Features
+
+* add --limit and --skip-unassigned flags to jump report commands ([d0ff2ae](https://github.com/appydave/appydave-tools/commit/d0ff2aeae4edffc81448e62502c3974a0942559f))
+
 ## [0.74.1](https://github.com/appydave/appydave-tools/compare/v0.74.0...v0.74.1) (2026-02-04)
 
 

data/CLAUDE.md

@@ -2,34 +2,13 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## ⚠️ PENDING: Quality Assurance Process Required
+## ✅ COMPLETE: DAM Enhancement Sprint QA (2025-01-22)
 
-**Action Required:** Two-phase validation for 75-commit DAM enhancement sprint
+Two-phase validation for the 75-commit DAM enhancement sprint (9e49668 → 4228b51) is complete.
 
-### Phase 1: Behavioral Regression Audit (MUST RUN FIRST)
-
-- **Instruction Guide:** [docs/ai-instructions/behavioral-regression-audit.md](./docs/ai-instructions/behavioral-regression-audit.md)
-- **Commit Range:** `9e49668` (baseline - known working) → `4228b51` (current - unknown state)
-- **Purpose:** Verify core functionality unchanged except for intentional UX improvements
-- **Method:** Two-snapshot comparison (not 75 individual commits)
-- **5 Phases:** Change inventory → Critical path → Behavioral testing → Logic diff → Spot-check
-- **Output:** `docs/code-quality/behavioral-audit-2025-01-22.md`
-- **Status:** Ready to execute - awaiting user confirmation
-- **Priority:** CRITICAL - Must complete before UAT
-
-### Phase 2: User Acceptance Testing (RUN AFTER REGRESSION AUDIT)
-
-- **UAT Plan:** [docs/code-quality/uat-plan-2025-01-22.md](./docs/code-quality/uat-plan-2025-01-22.md)
-- **Test Suites:** 4 suites, 20 tests (Core functionality, New features, Edge cases, Performance)
-- **Purpose:** Validate final state after regression fixes
-- **Status:** Ready to execute - run after Phase 1 completes
-- **Priority:** High - Final validation before release
-
-### Execution Order
-
-1. **Behavioral Regression Audit** → Identify and fix any breaking changes
-2. **User Acceptance Testing** → Validate everything works as designed
-3. **Ship it** → Merge/release with confidence
+- **Phase 1 — Behavioral Regression Audit:** ✅ SAFE — 0 regressions, 15+ UX improvements validated. See [docs/code-quality/behavioral-audit-2025-01-22.md](./docs/code-quality/behavioral-audit-2025-01-22.md)
+- **Phase 2 — UAT:** ✅ PASSED — 20/20 tests passed, 4 minor formatting issues found and fixed inline. See [docs/code-quality/uat-report-2025-01-22.md](./docs/code-quality/uat-report-2025-01-22.md)
+- **Current baseline:** 748 examples, 0 failures, 84.88% line coverage
 
 **Also Available:** Code quality retrospective analysis guide at [docs/ai-instructions/code-quality-retrospective.md](./docs/ai-instructions/code-quality-retrospective.md)
 

data/bin/dam

@@ -297,8 +297,7 @@ class VatCLI
     puts '📋 Summary - Generated Manifests:'
     puts ''
 
-    successful = results.select { |r| r[:success] }
-    failed = results.reject { |r| r[:success] }
+    successful, failed = results.partition { |r| r[:success] }
 
     successful.each do |result|
       brand_display = result[:brand].ljust(15)
@@ -1567,8 +1566,7 @@ class VatCLI
     puts '📋 Summary - S3 Scans:'
     puts ''
 
-    successful = results.select { |r| r[:success] }
-    failed = results.reject { |r| r[:success] }
+    successful, failed = results.partition { |r| r[:success] }
 
     successful.each do |result|
       brand_display = result[:brand].ljust(15)

data/bin/gpt_context.rb

@@ -19,57 +19,100 @@ options = Appydave::Tools::GptContext::Options.new(
 )
 
 OptionParser.new do |opts|
-  opts.banner = 'Usage: gather_content.rb [options]'
+  opts.banner = <<~BANNER
+    GPT Context Gatherer - Collect project files for AI context
 
-  opts.on('-i', '--include PATTERN', 'Pattern or file to include (can be used multiple times)') do |pattern|
+    SYNOPSIS
+        gpt_context [options]
+
+    DESCRIPTION
+        Collects and packages codebase files for AI assistant context.
+        Outputs to clipboard (default), file, or stdout.
+
+  BANNER
+
+  opts.separator 'OPTIONS'
+  opts.separator ''
+
+  opts.on('-i', '--include PATTERN',
+          'Glob pattern for files to include (repeatable)',
+          'Example: -i "lib/**/*.rb" -i "bin/**/*.rb"') do |pattern|
     options.include_patterns << pattern
   end
 
-  opts.on('-e', '--exclude PATTERN', 'Pattern or file to exclude (can be used multiple times)') do |pattern|
+  opts.on('-e', '--exclude PATTERN',
+          'Glob pattern for files to exclude (repeatable)',
+          'Example: -e "spec/**/*" -e "node_modules/**/*"') do |pattern|
     options.exclude_patterns << pattern
   end
 
-  opts.on('-f', '--format FORMAT', 'Output format: content, tree, or json, if not provided then both are used') do |format|
+  opts.on('-f', '--format FORMATS',
+          'Output format(s): tree, content, json, aider, files',
+          'Comma-separated. Default: content',
+          'Example: -f tree,content') do |format|
     options.format = format
   end
 
-  opts.on('-l', '--line-limit LIMIT', 'Limit the number of lines included from each file') do |limit|
-    options.line_limit = limit.to_i
+  opts.on('-l', '--line-limit N', Integer,
+          'Limit lines per file (default: unlimited)') do |n|
+    options.line_limit = n
   end
 
-  # New option for specifying base directory
-  opts.on('-b', '--base-dir DIRECTORY', 'Set the base directory to gather files from') do |directory|
+  opts.on('-b', '--base-dir DIRECTORY',
+          'Set the base directory to gather files from') do |directory|
     options.working_directory = directory
   end
 
-  # Debug output options
-  opts.on('-d', '--debug [MODE]', 'Enable debug mode [none, info, params, debug]', 'none', 'info', 'params', 'debug') do |debug|
+  opts.on('-d', '--debug [MODE]', 'Enable debug mode [none, info, params, debug]',
+          'none', 'info', 'params', 'debug') do |debug|
     options.debug = debug || 'info'
   end
 
-  # Output targets: clipboard or file
-  opts.on('-o', '--output TARGET', 'Output target: clipboard, or a file path (can be used multiple times)') do |target|
+  opts.on('-o', '--output TARGET',
+          'Output target: clipboard, filename, or stdout',
+          'Default: clipboard. Repeatable for multiple targets.') do |target|
     options.output_target << target
   end
 
-  opts.on('-p', '--prompt MESSAGE', 'Message/prompt to include in aider format output') do |message|
+  opts.on('-p', '--prompt TEXT',
+          'Prompt text for aider format output') do |message|
     options.prompt = message
   end
 
-  opts.on_tail('-h', '--help', 'Show this message') do
-    puts opts
-    puts "\nExamples:"
-    puts "  #{File.basename($PROGRAM_NAME)} -i 'lib/**/*.rb' -e 'lib/excluded/**/*.rb' -d"
-    puts "  #{File.basename($PROGRAM_NAME)} --include 'src/**/*.js' --exclude 'src/vendor/**/*.js'"
+  opts.separator ''
+  opts.separator 'OUTPUT FORMATS'
+  opts.separator '    tree     - Directory tree structure'
+  opts.separator '    content  - File contents with headers (default)'
+  opts.separator '    json     - Structured JSON output'
+  opts.separator '    aider    - Aider CLI command format (requires -p)'
+  opts.separator '    files    - File paths only'
+  opts.separator ''
+  opts.separator 'EXAMPLES'
+  opts.separator '    # Gather Ruby library code for AI context'
+  opts.separator "    gpt_context -i 'lib/**/*.rb' -e 'spec/**/*' -d"
+  opts.separator ''
+  opts.separator '    # Project structure overview'
+  opts.separator "    gpt_context -i '**/*' -f tree -e 'node_modules/**/*'"
+  opts.separator ''
+  opts.separator '    # Save to file with tree and content'
+  opts.separator "    gpt_context -i 'src/**/*.ts' -f tree,content -o context.txt"
+  opts.separator ''
+  opts.separator '    # Generate aider command'
+  opts.separator "    gpt_context -i 'lib/**/*.rb' -f aider -p 'Add logging'"
+  opts.separator ''
+
+  opts.on('-v', '--version', 'Show version') do
+    puts "gpt_context version #{Appydave::Tools::VERSION}"
+    exit
+  end
 
-    puts ''
-    puts '  # Get GPT Context Gatherer code that is found in any folder (bin, lib & spec)'
-    puts "  #{File.basename($PROGRAM_NAME)} -i '**/*gather*.rb'"
+  opts.on_tail('-h', '--help', 'Show this help') do
+    puts opts
     exit
   end
 end.parse!
 
-if options.include_patterns.empty? && options.exclude_patterns.empty? && options.format.nil?
+if options.include_patterns.empty? && options.exclude_patterns.empty?
   script_name = File.basename($PROGRAM_NAME, File.extname($PROGRAM_NAME))
 
   puts 'No options provided to GPT Context. Please specify patterns to include or exclude.'

data/docs/backlog.md

@@ -10,7 +10,7 @@ Requirements tracking for AppyDave Tools development.
 |---|-------------|-------|--------|
 | 1 | FR-1: GPT Context token counting (see below) | 2025-12-06 | Pending |
 | 2 | FR-2: GPT Context AI-friendly help system (see below) | 2025-12-07 | Pending |
-| 3 | NFR-1: Improve test coverage for DAM commands | 2025-12-06 | Pending |
+| 3 | NFR-1: Improve test coverage for DAM commands | 2025-12-06 | ✅ Addressed in DAM sprint (Jan 2025) — +648 lines, 5 new spec files |
 | 4 | FR-3: Jump Location Tool (see spec) | 2025-12-13 | ✅ Implemented 2025-12-13 |
 | 5 | NFR-2: Claude Code Skill for Jump Tool (see below) | 2025-12-14 | ✅ Implemented 2025-12-14 |
 | 6 | BUG-1: Jump CLI get/remove commands fail to find entries (see below) | 2025-12-15 | Pending |

data/docs/code-quality/README.md

@@ -34,22 +34,21 @@ This directory contains code quality retrospective analyses and improvement plan
 
 ---
 
-## Current Status
-
-### Critical Issues (3)
-1. ⏳ **Git Operations Duplication** - 90 lines across 3 files
-2. ⏳ **Configuration Loading Pattern** - 20+ redundant calls (partially fixed)
-3. ⏳ **Brand Resolution Logic** - Scattered across 5+ files, causing bugs
-
-### Moderate Issues (3)
-1. ⏳ **Test Pattern Inconsistency** - Mix of mocking vs real filesystem
-2. ⏳ **Error Handling Inconsistency** - 3 different patterns
-3. ⏳ **Directory Utils Duplication** - 40 lines duplicated
-
-### Implementation Priority
-1. **High Priority** - GitHelper extraction, BrandResolver creation
-2. **Medium Priority** - Exception hierarchy, test refactoring
-3. **Low Priority** - Documentation, minor cleanups
+## Current Status (updated 2026-03-19)
+
+### ✅ Resolved in DAM Enhancement Sprint (Jan 2025)
+1. ✅ **Git Operations Duplication** → extracted to `lib/appydave/tools/dam/git_helper.rb`
+2. ✅ **Brand Resolution Logic** → centralized in `lib/appydave/tools/dam/brand_resolver.rb`
+3. ✅ **Error Handling Inconsistency** → exception hierarchy in `lib/appydave/tools/dam/errors.rb`
+4. ✅ **Directory Utils Duplication** → extracted to `lib/appydave/tools/dam/file_helper.rb`
+5. ✅ **Test Pattern Inconsistency** → `project_listing_spec.rb` refactored to use shared filesystem context
+
+### ⏳ Still Outstanding (Low Priority)
+1. ⏳ **Configuration Loading Redundancy** — `Config.configure` called ~7x in config.rb (memoized, safe, but noisy). See BACKLOG.md B011.
+2. ⏳ **CLI Argument Parsing** — `bin/dam` has multiple 200+ line methods. See BACKLOG.md B011.
+3. ⏳ **Integration Tests** — Brand resolution tested unit-only, no end-to-end cross-layer specs. See BACKLOG.md B012.
+
+**Baseline:** 748 examples, 0 failures, 84.88% coverage
 
 ---
 

data/docs/planning/AGENTS.md

@@ -0,0 +1,245 @@
+# AGENTS.md — AppyDave Tools
+
+> Operational knowledge for every background agent. Self-contained — you receive only this file + your work unit prompt.
+> Last updated: 2026-03-19 (derived from actual files, not guesswork)
+
+---
+
+## Project Overview
+
+**What:** Ruby gem providing CLI productivity tools for AppyDave's YouTube content creation workflow.
+**Stack:** Ruby 3.4.2, Bundler 2.6.2, RSpec, RuboCop, semantic-release CI/CD.
+**Active area:** DAM (Digital Asset Management) — `lib/appydave/tools/dam/` — is the primary focus of recent campaigns.
+**Commits:** Trigger automated semantic versioning via GitHub Actions. Always use `kfeat`/`kfix` — never `git commit`.
+
+---
+
+## Build & Run Commands
+
+```bash
+# Initialize rbenv (required if rbenv not in PATH)
+eval "$(rbenv init -)"
+
+# Run tests
+bundle exec rspec                           # All tests
+bundle exec rspec spec/path/to/file_spec.rb # Single file
+RUBYOPT="-W0" bundle exec rspec             # Suppress Ruby 3.4 platform warnings
+
+# Lint
+bundle exec rubocop --format clang          # Standard lint check (matches CI)
+
+# Commit (never use git commit directly)
+kfeat "add feature description"             # Minor version bump
+kfix "fix bug description"                  # Patch version bump
+```
+
+**Baseline (2026-03-19):** 748 examples, 0 failures, 84.88% line coverage (7680/9048)
+
+---
+
+## Directory Structure
+
+```
+bin/                          CLI scripts (development, .rb extension)
+exe/                          Thin wrappers for gem installation (no .rb extension)
+lib/appydave/tools/
+  dam/                        Digital Asset Management — main active area
+    brand_resolver.rb         Centralizes ALL brand name transformations (appydave ↔ v-appydave)
+    errors.rb                 Custom exception hierarchy (DamError, BrandNotFoundError, etc.)
+    fuzzy_matcher.rb          Levenshtein distance for "did you mean?" suggestions
+    git_helper.rb             Extracted git command wrappers (current_branch, commits_ahead, etc.)
+    file_helper.rb            File utility methods (directory size, format_size)
+    config.rb                 Delegates brand resolution to BrandResolver; memoized Config loading
+    project_resolver.rb       Project name resolution with regex pattern matching
+    project_listing.rb        Table display for `dam list` command (format() for headers + data)
+    s3_operations.rb          S3 upload/download/status with MD5 comparison
+    status.rb                 Project git/S3 status display
+    manifest_generator.rb     Video project manifest
+    sync_from_ssd.rb          SSD sync operations
+    ssd_status.rb             SSD backup status
+    repo_push.rb, repo_status.rb, repo_sync.rb, share_operations.rb, config_loader.rb, s3_scanner.rb
+  configuration/              Config file management (settings.json, channels.json)
+  gpt_context/                File collection for AI context gathering
+  subtitle_processor/         SRT file cleaning and joining
+  youtube_manager/            YouTube API integration
+  name_manager/               Jump location tool (fuzzy search, CRUD, alias generation)
+  types/                      BaseModel, ArrayType, HashType, IndifferentAccessHash
+spec/
+  appydave/tools/dam/         14 spec files (one per dam/ class)
+  support/
+    dam_filesystem_helpers.rb Shared contexts for DAM filesystem testing
+    jump_test_helpers.rb      Jump tool test helpers
+docs/
+  backlog.md                  Legacy requirements (BACKLOG.md in this folder supersedes)
+  code-quality/               Audit reports (behavioral-audit-2025-01-22, uat-report-2025-01-22)
+  planning/                   Ralphy campaign artifacts (this folder)
+  architecture/               CLI patterns, testing patterns, configuration systems
+```
+
+---
+
+## Success Criteria
+
+Every work unit must satisfy ALL of the following before marking `[x]`:
+
+- [ ] `bundle exec rspec` — 748+ examples, 0 failures
+- [ ] `bundle exec rubocop --format clang` — 0 offenses
+- [ ] Line coverage stays ≥ 84.88%
+- [ ] Any new functionality has ≥ 1 spec covering it
+- [ ] All new `.rb` files start with `# frozen_string_literal: true`
+- [ ] No hardcoded brand transformation strings (always use BrandResolver)
+
+---
+
+## Reference Patterns
+
+### Shared Context for DAM Specs — THE STANDARD PATTERN
+
+```ruby
+# spec/appydave/tools/dam/some_class_spec.rb
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Appydave::Tools::Dam::SomeClass do
+  include_context 'with vat filesystem and brands', brands: %w[appydave voz]
+
+  before do
+    FileUtils.mkdir_p(File.join(appydave_path, 'b65-test-project'))
+    FileUtils.mkdir_p(File.join(voz_path, 'boy-baker'))
+  end
+
+  describe '.some_method' do
+    it 'does the thing' do
+      expect(described_class.some_method('appydave')).to eq('expected')
+    end
+  end
+end
+```
+
+**Available from shared context:**
+- `temp_folder` — temp root (auto-cleaned after each example)
+- `projects_root` — `/path/to/temp/video-projects`
+- `appydave_path`, `voz_path`, etc. — brand dirs (created on demand)
+- `SettingsConfig#video_projects_root` is mocked to return `projects_root`
+
+### BrandResolver — All Brand Name Transformations
+
+```ruby
+BrandResolver.expand('appydave')      # => 'v-appydave'
+BrandResolver.expand('ad')            # => 'v-appydave' (shortcut)
+BrandResolver.expand('joy')           # => 'v-beauty-and-joy'
+BrandResolver.normalize('v-appydave') # => 'appydave'
+BrandResolver.to_config_key('ad')     # => 'appydave'
+BrandResolver.to_display('voz')       # => 'v-voz'
+BrandResolver.validate('appydave')    # => 'appydave' or raises BrandNotFoundError
+BrandResolver.exists?('appydave')     # => true/false
+```
+
+### Typed Exception Pattern
+
+```ruby
+# Use errors from lib/appydave/tools/dam/errors.rb
+raise ProjectNotFoundError, 'Project name is required' if project_hint.nil?
+raise BrandNotFoundError.new(brand, available_brands, fuzzy_suggestions)
+
+# Exception hierarchy:
+# DamError < StandardError
+#   BrandNotFoundError < DamError
+#   ProjectNotFoundError < DamError
+#   ConfigurationError < DamError
+#   S3OperationError < DamError
+#   GitOperationError < DamError
+```
+
+### Table Display — Headers Must Use format()
+
+```ruby
+# CORRECT — headers and data use same format string
+header = format('%-45s %12s %15s %10s', 'PROJECT', 'SIZE', 'AGE', 'GIT')
+row    = format('%-45s %12s %15s %10s', name,      size,   age,  git_status)
+
+# WRONG — hardcoded header string causes misalignment
+header = 'PROJECT        SIZE    AGE     GIT'
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ Inline brand transformations — never write `"v-#{brand}"` or `.sub(/^v-/, '')` outside BrandResolver
+- ❌ Mocking Config class methods in DAM specs — use `include_context 'with vat filesystem and brands'` instead
+- ❌ `raise 'string error'` in DAM module — use typed exceptions from `errors.rb`
+- ❌ Duplicating git command methods — use `GitHelper` module
+- ❌ Duplicating file size calculations — use `FileHelper` module
+- ❌ `include FileUtils` (conflicts with Ruby stdlib) — use dam's `FileHelper`
+- ❌ Hardcoded header strings for table output — always use `format()` with same format string as data rows
+
+---
+
+## Mock Patterns
+
+### External Services — DO Mock
+
+```ruby
+# S3 calls — use WebMock or VCR cassettes
+stub_request(:get, /s3\.amazonaws\.com/).to_return(body: '...')
+
+# YouTube API — VCR cassettes in spec/fixtures/vcr_cassettes/
+VCR.use_cassette('youtube/get_video') do
+  # make API call
+end
+```
+
+### Internal DAM Classes — DON'T Mock
+
+Use real temp filesystem via shared context instead. The only acceptable mock inside DAM specs:
+- `SettingsConfig#video_projects_root` — already mocked by the shared context
+- `Config.available_brands` — acceptable when testing "no brands found" edge case
+
+### Config.configure — Safe to Call Multiple Times
+
+```ruby
+# Config.configure is memoized — idempotent, no-op after first call
+# Called in multiple places across DAM module; this is known/acceptable technical debt
+Appydave::Tools::Configuration::Config.configure
+```
+
+---
+
+## Quality Gates
+
+- **Tests:** `bundle exec rspec` — 748 examples, 0 failures (do not ship if any fail)
+- **Lint:** `bundle exec rubocop --format clang` — 0 offenses (CI will reject)
+- **Coverage:** ≥ 84.88% line coverage
+- **frozen_string_literal:** Required on every new `.rb` file
+- **Commit format:** `kfeat`/`kfix` only — triggers semantic versioning + CI wait
+
+---
+
+## Learnings
+
+### From DAM Enhancement Sprint (Jan 2025 — 75 commits, 9e49668 → 4228b51)
+
+- **BrandResolver is the critical path.** All `dam` commands flow through it. Any change to brand resolution must be tested with all shortcuts (ad, joy, ss, voz, aitldr, kiros) and case variations (APPYDAVE, AppyDave).
+- **`Regexp.last_match` is reset by `.sub()` calls.** Always capture regex groups BEFORE any string transformation: `project = ::Regexp.last_match(2)` then `brand_key = BrandResolver.normalize(brand_with_prefix)`.
+- **`Config.configure` is memoized but called redundantly.** ~7 calls in config.rb, plus more in other files. Known issue, not worsened. Don't add new calls; reference existing ones.
+- **FuzzyMatcher threshold is 3 (Levenshtein distance).** Wired via `Config#brand_path` → `FuzzyMatcher.find_matches(brand_key, all_brand_identifiers, threshold: 3)`. Works for "appydav" → "appydave".
+- **Performance: ~2s per project** for git/S3 checks during `dam list`. 13 projects = ~26s total. Acceptable. Grows linearly — flag if brand has > 20 projects.
+- **Table format() pattern is non-obvious.** Headers misaligned 3 times in UAT before fix. Always verify with real data that has long names (e.g., "beauty-and-joy" = 14 chars).
+- **Test strategy:** 5 new spec files (+648 lines) added for DAM helper classes. `project_listing_spec.rb` refactored from 20 Config mocks to shared filesystem context. Task 3.1 complete.
+
+### From Jump Location Tool (Dec 2025)
+
+- **Dependency injection for path validators** is required for CI compatibility. Path existence checks fail in CI — inject via parameter, not hardcoded.
+- **BUG-1 status (as of 2026-03-19 audit):** Static analysis shows `Jump::Config#find` and `Commands::Remove` both have correct dual-key guards (`loc.key == key` on Location objects; `loc['key'] == key || loc[:key] == key` on raw hashes). The bug may be environmental or already fixed. Always verify live before writing fix code.
+- **Jump Commands layer is undertested:** `Commands::Remove`, `Commands::Add`, `Commands::Update` have zero dedicated specs. Auto-regenerate CLI spec does not substitute for command-layer unit tests verifying `--force` guards, error codes, and suggestion logic (see B018).
+- **Jump report commands** got `--limit` and `--skip-unassigned` flags after initial implementation. Jump tool scope grows incrementally.
+
+### From Three-Lens Audit (2026-03-19)
+
+- **`file_collector.rb` has two landmines before FR-2:** `puts @working_directory` at line 15 pollutes stdout; `FileUtils.cd` without `ensure` leaves process in wrong directory on exception. Fix both before adding any code to this class.
+- **ManifestGenerator and SyncFromSsd produce incompatible range strings (B016).** `determine_range('b65')` returns `"b50-b99"` in one and `"60-69"` in the other. This is a data integrity bug for SSD archive path construction. Do not add new archive features before this is resolved.
+- **`ssl_verify_peer: false` is set unconditionally in S3Operations and ShareOperations (B017).** Not safe despite the comment. Remove before adding any new S3 functionality.
+- **`Config.configure` fires inside nested call chains** (e.g., `brand_path` → `BrandResolver.to_config_key` → `configure` = 3 calls for one operation). Memoized, so no performance cost, but pattern will spread if not watched. Do not add new `Config.configure` calls; reference from the existing top-level call.
+- **BUG-1 is NOT in `name_manager/`.** Jump's `name_manager/project_name.rb` is a different unrelated class. BUG-1 root is in `lib/appydave/tools/jump/` (Config, Search, Commands).