appydave-tools 0.75.0 → 0.76.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e45ff57b507a705f826281a7d361abf0724d719eaf1c1ba4795198f3a4551a7f
-  data.tar.gz: edfc8fcdb775c290d9c59a588215de3e2c613075ee49332836bf19de92a5126b
+  metadata.gz: 39c3338d4f56e9b453669e54150db39c4449b667fa347a2634b2741fbd272235
+  data.tar.gz: 5949d3218ac0ca10376e9307ee981fd88a9505d876ba88178a7a6647447b8077
 SHA512:
-  metadata.gz: d5d45772ed9304ac22cca51417c0d48b0d176d824933feaafbc4a34c50ff8585bbce93a4f423ecadc39ac64aeca5e0e2724556a1407c428a318fa86926a65899
-  data.tar.gz: ab16611805c302aeb6fe1930e3502d4330cb00833bd282e2631e9cbb25f6fc179eb66c7e6cd4535a89005cd743cc0db6c3e9eaaaeea0a22c671274e5b6f9b43d
+  metadata.gz: 9b52b37eb3e5ebda0eb8508f054b53cf607b208e2ba2c227418381bc77940720741c7feea5e9edc47ca8942da0c5bb4e20d79034d8b3e345ad10f0823bedd76a
+  data.tar.gz: 6aed7f6c4d2d16b7706d6449ba3759e5b24cc08d3ac602c979485babc72625d632588ebf070211e9b68a11d5af5a75151d4b6a92729c50a8335a59a1040d919d

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [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,52 +19,95 @@ 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!

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).

data/docs/planning/BACKLOG.md

@@ -0,0 +1,186 @@
+# Project Backlog — AppyDave Tools
+
+**Last updated**: 2026-03-19 (updated after three-lens audit)
+**Total**: 20 | Pending: 14 | Done: 6 | Deferred: 0 | Rejected: 0
+
+---
+
+## Pending
+
+### High Priority
+- [ ] B015 — BUG-2: FileCollector uses FileUtils.cd without ensure (process dir not restored on exception) | Priority: high
+- [ ] B016 — BUG-3: ManifestGenerator + SyncFromSsd produce incompatible SSD range strings (data integrity) | Priority: high
+- [ ] B002 — FR-2: GPT Context AI-friendly help system | Priority: high
+- [x] B006 — BUG-1: Jump CLI get/remove key lookup | Completed: verified fixed 2026-03-19, regression spec added
+- [ ] B017 — Security: ssl_verify_peer disabled unconditionally in S3Operations + ShareOperations | Priority: high
+
+### Medium Priority
+- [ ] B018 — Tests: add specs for Jump Commands::Remove, Commands::Add, Commands::Update | Priority: medium
+- [ ] B019 — Fix: remove debug puts @working_directory from gpt_context/file_collector.rb | Priority: medium
+- [ ] B001 — FR-1: GPT Context token counting | Priority: medium
+- [ ] B012 — Arch: add integration tests for brand resolution end-to-end | Priority: medium
+
+### Low Priority
+- [ ] B007 — Performance: parallel git/S3 status checks for dam list | Priority: low
+- [ ] B008 — Performance: cache git/S3 status with 5-min TTL | Priority: low
+- [ ] B009 — UX: progress indicators for dam operations > 5s | Priority: low
+- [ ] B010 — UX: auto-adjust dam table column widths to terminal width | Priority: low
+- [ ] B011 — Arch: extract VatCLI business logic from bin/dam (1,600-line God class) | Priority: low
+- [ ] B020 — Arch: split S3Operations (1,030 lines, mixed I/O + logic) | Priority: low
+
+---
+
+## Done
+
+- [x] B003 — NFR-1: Improve DAM test coverage | Completed: dam-enhancement-sprint (Jan 2025)
+- [x] B004 — FR-3: Jump Location Tool | Completed: 2025-12-13
+- [x] B005 — NFR-2: Jump Claude Code Skill | Completed: 2025-12-14
+- [x] B013 — Arch: Extract GitHelper module (90 lines duplication) | Completed: dam-enhancement-sprint (Jan 2025)
+- [x] B014 — Arch: Create BrandResolver to centralize brand transformation | Completed: dam-enhancement-sprint (Jan 2025)
+
+---
+
+## Item Details
+
+### B001 — FR-1: GPT Context Token Counting
+
+**User Story**: As a developer using GPT Context, I want to see estimated token counts so I can ensure my context fits within LLM limits.
+
+**Acceptance Criteria:**
+- [ ] Display estimated token count in output
+- [ ] Support common tokenizers (cl100k for GPT-4, claude for Claude)
+- [ ] Show warning when exceeding common thresholds (100k, 200k)
+- [ ] Optional via `--tokens` flag
+
+**Notes:** Consider tiktoken gem for OpenAI tokenization. May need to estimate for Claude (no official Ruby tokenizer).
+
+---
+
+### B002 — FR-2: GPT Context AI-Friendly Help System
+
+**Spec:** `docs/specs/fr-002-gpt-context-help-system.md`
+
+**User Story**: As an AI agent using GPT Context via skills, I want structured, comprehensive help output so I can understand all options and use the tool correctly.
+
+**Notes:** Full spec exists. High priority — enables AI skill integration.
+
+---
+
+### B006 — BUG-1: Jump CLI get/remove Key Lookup Bug
+
+**Priority:** High — but verify live first
+
+**⚠️ Three-lens audit (2026-03-19) found:** Static analysis of `Jump::Config#find`, `Config#remove`, and `Search#get` shows correct dual-key guards. Bug may be environmental (stale config file format) or already fixed in a prior commit. **Run `bin/jump.rb get <key>` live before writing any code.**
+
+**Steps to Reproduce:**
+```bash
+bin/jump.rb search awb-team   # ✅ finds entry
+bin/jump.rb get awb-team      # ❌ "Location not found"  ← confirm this still fails
+bin/jump.rb remove test-minimal --force  # ❌ "No locations found."
+```
+
+**If bug confirmed:** Failure site is in `Jump::Config#find` (`loc.key == key`) or the memoization of `@locations` — NOT in `name_manager/`. The `Commands::Remove#run` → `config.find(key)` → `locations.find { |loc| loc.key == key }` path is the call chain to trace.
+
+**Acceptance Criteria:**
+- [ ] Confirm bug still exists live (if not, write regression spec and close)
+- [ ] `get <key>` finds entry when `search <key>` finds it
+- [ ] `remove <key>` finds entry when `search <key>` finds it
+- [ ] Regression tests for key lookup consistency
+- [ ] Root cause documented in commit message
+
+---
+
+### B007 — Performance: Parallel git/S3 Status Checks
+
+**Context:** `dam list appydave` with 13 projects takes ~26s (sequential git+S3 check per project).
+**Suggested:** Parallel status checks using Ruby threads or concurrent-ruby.
+**Source:** UAT report 2025-01-22 post-release recommendations.
+
+---
+
+### B008 — Performance: Cache git/S3 Status
+
+**Context:** Same sequential bottleneck as B007. Complementary approach.
+**Suggested:** Cache git/S3 status per project with 5-minute TTL.
+**Source:** UAT report 2025-01-22 post-release recommendations.
+
+---
+
+### B009 — UX: Progress Indicators
+
+**Context:** Operations taking > 5s show no feedback.
+**Suggested:** Spinner or "checking project 3/13..." output for long-running dam commands.
+**Source:** UAT report 2025-01-22 post-release recommendations.
+
+---
+
+### B010 — UX: Auto-Adjust Table Column Widths
+
+**Context:** Column widths are hardcoded (e.g., KEY column = 15 chars). Terminal resizing or very long names cause misalignment.
+**Suggested:** Detect terminal width and/or measure data to set column widths dynamically.
+**Source:** UAT report 2025-01-22 post-release recommendations.
+
+---
+
+### B011 — Arch: Extract VatCLI Business Logic from bin/dam
+
+**Context:** `bin/dam` is 1,600 lines. Methods `scan_single_brand_s3`, `add_local_sync_status!`, `display_s3_scan_table`, `parse_s3_args`, `format_bytes` are business/display logic that belongs in library classes. 20+ rubocop-disable comments are symptoms.
+**Suggested:** Extract to library classes before adding DAM parallelism (B007/B008) — those features cannot be built cleanly in VatCLI.
+**Source:** Architectural review 2026-03-19, Critical concern #1.
+
+---
+
+### B012 — Arch: Integration Tests for Brand Resolution
+
+**Context:** BrandResolver, Config, ProjectResolver interact across layers. Unit tests cover each individually but no end-to-end test catches cross-layer bugs.
+**Suggested:** Integration specs that test brand → project resolution across the full call chain.
+**Source:** Code quality report 2025-01-21 + architectural review 2026-03-19.
+
+---
+
+### B015 — BUG-2: FileCollector FileUtils.cd Without ensure
+
+**Context:** `lib/appydave/tools/gpt_context/file_collector.rb` line 20 calls `FileUtils.cd(@working_directory)`. If an exception fires inside `build`, the process working directory is never restored to `Dir.home`. Affects any subsequent operation in the same process.
+**Fix:** Wrap in block form: `FileUtils.cd(@working_directory) { ... }` — Ruby handles restore automatically. Or add `ensure FileUtils.cd(Dir.home)`.
+**Blocker for:** FR-2 — fix this before adding more code paths to `file_collector.rb`.
+**Source:** Code quality audit 2026-03-19, MAJOR issue #2.
+
+---
+
+### B016 — BUG-3: ManifestGenerator vs SyncFromSsd Incompatible Range Strings
+
+**Context:** `ManifestGenerator.determine_range('b65')` returns `"b50-b99"`. `SyncFromSsd.determine_range('b65')` returns `"60-69"`. Both are used to construct SSD archive folder paths. Projects archived via SSD sync won't be found by the manifest generator, and vice versa. A `find_ssd_project_path` fallback scan may paper over this in practice.
+**Fix:** Standardise both methods on one format. Decide which format matches actual SSD folder structure on disk, then update the other method to match.
+**Source:** Code quality audit 2026-03-19, MAJOR issue #1.
+
+---
+
+### B017 — Security: ssl_verify_peer Disabled in S3Operations + ShareOperations
+
+**Context:** `lib/appydave/tools/dam/s3_operations.rb` lines 110-113 and `share_operations.rb` lines 97-100 set `ssl_verify_peer: false` unconditionally. Comment claims "safe for AWS S3" — this is incorrect. Disabling peer verification removes MITM protection on all S3 operations including AWS credential transmission.
+**Fix:** Remove the `ssl_verify_peer: false` override entirely. AWS SDK handles SSL correctly by default. If there was a historical reason (corporate proxy, dev cert issue), document it and scope to `ENV['AWS_SKIP_SSL'] == 'true'` only.
+**Source:** Code quality audit 2026-03-19, MAJOR issue #3.
+
+---
+
+### B018 — Tests: Jump Commands Layer Has No Dedicated Specs
+
+**Context:** `Commands::Remove`, `Commands::Add`, `Commands::Update` have zero unit specs. The CLI spec only tests auto-regenerate side effects. `--force` guard, error codes, suggestion-on-not-found logic, and key nil-handling in these commands are entirely untested.
+**Fix:** Add `spec/appydave/tools/jump/commands/remove_spec.rb`, `add_spec.rb`, `update_spec.rb`. Use `JumpTestLocations` factory + `with jump filesystem` context.
+**Source:** Test quality audit 2026-03-19, RISK-1.
+
+---
+
+### B019 — Fix: Remove Debug puts From file_collector.rb
+
+**Context:** `lib/appydave/tools/gpt_context/file_collector.rb` line 15: `puts @working_directory`. Prints working directory on every `gpt_context` invocation. Pollutes captured output. Must be removed before FR-2 adds help system output.
+**Fix:** Delete line 15.
+**Source:** Code quality audit 2026-03-19, MINOR issue #4.
+
+---
+
+### B020 — Arch: Split S3Operations (1,030 lines)
+
+**Context:** `S3Operations` handles upload, download, status, cleanup, archive to SSD, MD5 comparison, content type detection, file formatting, and time formatting — all in one class with direct `puts` throughout. No result objects returned from upload/download/cleanup (void methods with side effects).
+**Suggested:** Split into at minimum `S3Uploader`, `S3Downloader`, `S3StatusChecker`, `S3Archiver` with I/O separated from computation. Required before B007 (parallelism) can be built.
+**Source:** Architectural review 2026-03-19, Critical concern #2.

data/docs/planning/fr2-gpt-context-help/AGENTS.md

@@ -0,0 +1,256 @@
+# AGENTS.md — fr2-gpt-context-help
+
+> Operational knowledge for this campaign's background agents.
+> Inherited from docs/planning/AGENTS.md (2026-03-19). Campaign-specific additions below.
+> Self-contained — you receive only this file + your work unit prompt.
+
+---
+
+## 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.
+**This campaign:** FR-2 — enhance `bin/gpt_context.rb` OptionParser with structured help system. One file. No lib/ changes.
+**Commits:** 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/appydave/tools/gpt_context/       # GPT context specs only
+RUBYOPT="-W0" bundle exec rspec                          # Suppress Ruby 3.4 platform warnings
+
+# Lint
+bundle exec rubocop --format clang                       # Standard lint check (matches CI)
+
+# Manual verification
+bin/gpt_context.rb --help                                # Should show structured help
+bin/gpt_context.rb --version                             # Should show version
+bin/gpt_context.rb -v                                    # Short version flag
+bin/gpt_context.rb --help | grep -E "^(SYNOPSIS|DESCRIPTION|OPTIONS|OUTPUT FORMATS|EXAMPLES)"
+
+# Commit (never use git commit directly)
+kfeat "add AI-friendly help system to GPT Context"       # Use this exact message
+```
+
+**Baseline (2026-03-19):** 748 examples, 0 failures, 84.88% line coverage (7680/9048)
+
+---
+
+## Directory Structure
+
+```
+bin/gpt_context.rb                              ← THE ONLY FILE TO CHANGE
+lib/appydave/tools/gpt_context/
+  file_collector.rb                             Read-only reference (DO NOT MODIFY)
+  options.rb                                    Read-only reference (DO NOT MODIFY)
+  output_handler.rb                             Read-only reference (DO NOT MODIFY)
+lib/appydave/tools/version.rb                   Read-only — VERSION constant lives here
+spec/appydave/tools/gpt_context/
+  cli_spec.rb                                   ← CREATE THIS (new file)
+  file_collector_spec.rb                        Existing — do not modify
+```
+
+---
+
+## Success Criteria
+
+Every work unit must satisfy ALL before marking `[x]`:
+
+- [ ] `bundle exec rspec` — 748+ examples, 0 failures (new specs add to this count)
+- [ ] `bundle exec rubocop --format clang` — 0 offenses
+- [ ] Line coverage stays ≥ 84.88%
+- [ ] `bin/gpt_context.rb --help` output includes SYNOPSIS, DESCRIPTION, OPTIONS, OUTPUT FORMATS, EXAMPLES sections
+- [ ] `bin/gpt_context.rb --version` outputs `gpt_context version X.Y.Z`
+- [ ] `spec/appydave/tools/gpt_context/cli_spec.rb` exists with ≥ 3 passing tests
+- [ ] Banner no longer says `gather_content.rb` — it says `gpt_context`
+- [ ] `# frozen_string_literal: true` at top of new spec file
+
+---
+
+## Work Unit Spec
+
+### fr2-gpt-context-help — Implement AI-friendly help system
+
+**File to modify:** `bin/gpt_context.rb`
+
+**What to do:**
+
+1. Replace the `opts.banner` line with a heredoc banner containing Synopsis and Description sections
+2. Add `opts.separator` calls for OUTPUT FORMATS and EXAMPLES sections after the options
+3. Add `--version` / `-v` flag before the `--help` flag
+4. Enhance each option's description to include defaults and examples (multi-line array format)
+5. Fix the banner script name: currently `gather_content.rb` → should be `gpt_context`
+
+**Full implementation pattern** (from spec, Option A):
+
+```ruby
+OptionParser.new do |opts|
+  opts.banner = <<~BANNER
+    GPT Context Gatherer - Collect project files for AI context
+
+    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',
+          'Glob pattern for files to exclude (repeatable)',
+          'Example: -e "spec/**/*" -e "node_modules/**/*"') do |pattern|
+    options.exclude_patterns << pattern
+  end
+
+  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('-o', '--output TARGET',
+          'Output target: clipboard, filename, or stdout',
+          'Default: clipboard. Repeatable for multiple targets.') do |target|
+    options.output_target << target
+  end
+
+  opts.on('-d', '--debug [MODE]', 'Enable debug mode [none, info, params, debug]',
+          'none', 'info', 'params', 'debug') do |debug|
+    options.debug = debug || 'info'
+  end
+
+  opts.on('-l', '--line-limit N', Integer,
+          'Limit lines per file (default: unlimited)') do |n|
+    options.line_limit = n
+  end
+
+  opts.on('-b', '--base-dir DIRECTORY',
+          'Set the base directory to gather files from') do |directory|
+    options.working_directory = directory
+  end
+
+  opts.on('-p', '--prompt TEXT',
+          'Prompt text for aider format output') do |message|
+    options.prompt = message
+  end
+
+  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
+
+  opts.on_tail('-h', '--help', 'Show this help') do
+    puts opts
+    exit
+  end
+end.parse!
+```
+
+**New spec file** `spec/appydave/tools/gpt_context/cli_spec.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe 'gpt_context CLI help' do
+  let(:script) { File.expand_path('../../../../bin/gpt_context.rb', __dir__) }
+
+  describe '--help' do
+    subject(:output) { `ruby #{script} --help 2>&1` }
+
+    it 'includes SYNOPSIS section' do
+      expect(output).to include('SYNOPSIS')
+    end
+
+    it 'includes EXAMPLES section' do
+      expect(output).to include('EXAMPLES')
+    end
+
+    it 'includes OUTPUT FORMATS section' do
+      expect(output).to include('OUTPUT FORMATS')
+    end
+  end
+
+  describe '--version' do
+    it 'shows version number' do
+      output = `ruby #{script} --version 2>&1`
+      expect(output).to match(/gpt_context version \d+\.\d+\.\d+/)
+    end
+  end
+end
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ Do NOT modify any file in `lib/` — this campaign is bin/ only
+- ❌ Do NOT use `opts.on_tail` for `--version` (use `opts.on` so it appears before `--help` in output)
+- ❌ Do NOT leave the banner saying `gather_content.rb`
+- ❌ Do NOT require spec_helper explicitly — it's auto-required via `.rspec` config
+- ❌ Do NOT use `system()` or backticks in specs to call the script with a path that includes spaces
+
+---
+
+## Quality Gates
+
+- **Tests:** `bundle exec rspec` — 748+ examples, 0 failures
+- **Lint:** `bundle exec rubocop --format clang` — 0 offenses
+- **Coverage:** ≥ 84.88% line coverage
+- **Manual:** `bin/gpt_context.rb --help` and `--version` work as expected
+- **Commit format:** `kfeat "add AI-friendly help system to GPT Context"`
+
+---
+
+## Learnings (inherited)
+
+### From Three-Lens Audit (2026-03-19)
+- `file_collector.rb` pre-conditions (B015, B019) already fixed in commit 13d5f87 — do not re-fix
+- BUG-1 already verified fixed — do not re-investigate
+
+### From DAM Enhancement Sprint (Jan 2025)
+- `Config.configure` is memoized — idempotent
+- Table format() pattern: always use same format string for headers and data rows
+
+### From Jump Location Tool (Dec 2025)
+- Dependency injection for path validators required for CI compatibility
+- Jump Commands layer is undertested — not relevant to this campaign

data/docs/planning/fr2-gpt-context-help/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,24 @@
+# IMPLEMENTATION_PLAN.md — fr2-gpt-context-help
+
+**Goal**: Enhance GPT Context CLI with AI-friendly help system (FR-2)
+**Started**: 2026-03-19
+**Target**: `--help` shows structured sections; `--version` works; specs pass; rubocop clean
+
+## Summary
+- Total: 1 | Complete: 0 | In Progress: 0 | Pending: 1 | Failed: 0
+
+## Pending
+
+## In Progress
+- [~] fr2-gpt-context-help — Implement AI-friendly help system in bin/gpt_context.rb per docs/specs/fr-002-gpt-context-help-system.md
+
+## Complete
+
+## Failed / Needs Retry
+
+## Notes & Decisions
+- Pre-conditions already satisfied: B015 (FileUtils.cd) and B019 (debug puts) fixed in commit 13d5f87
+- Implementation is Option A from spec: enhanced OptionParser only — no changes to lib/
+- Fix banner script name while in there (currently says gather_content.rb, should say gpt_context)
+- New spec file: spec/appydave/tools/gpt_context/cli_spec.rb (3 tests minimum)
+- Commit with: kfeat "add AI-friendly help system to GPT Context"

data/docs/planning/next-round-brief.md

@@ -0,0 +1,55 @@
+# Next Round Brief
+
+**Created:** 2026-03-19
+**Updated:** 2026-03-19 (after three-lens audit)
+
+---
+
+## Recommended Next Campaign: gpt_context Fixes + FR-2 + Jump Verification
+
+### Goal
+
+Fix the two small blockers in `gpt_context/file_collector.rb` (B015, B019), then implement FR-2 (GPT Context AI help system). In parallel, verify whether BUG-1 (Jump get/remove) is still live before planning a Jump campaign.
+
+### Background
+
+**Three-lens audit findings changed the priority order:**
+
+1. FR-2 has two small pre-conditions in `file_collector.rb` that must be fixed first:
+   - `puts @working_directory` at line 15 (B019 — 1 line delete)
+   - `FileUtils.cd` without `ensure` (B015 — wrap in block form)
+   Both are ~5 minutes of work. Do them as the first commit of the FR-2 campaign.
+
+2. BUG-1 (Jump get/remove) is mislabeled in the original backlog. Static analysis shows `Jump::Config#find` and `Commands::Remove` have correct dual-key guards. The bug may already be fixed or may be environmental. **Verify live before planning any Jump campaign.**
+
+3. New high-priority bugs found by the audit (B016, B017) should be assessed for inclusion in the next campaign or scheduled shortly after.
+
+### Suggested Work Units (FR-2 Campaign)
+
+1. **Fix B019** — Delete `puts @working_directory` from `file_collector.rb:15` (1-line fix)
+2. **Fix B015** — Wrap `FileUtils.cd` in block form in `file_collector.rb` (3-line fix)
+3. **Implement FR-2** — Read `docs/specs/fr-002-gpt-context-help-system.md`. Option A from the spec (enhanced OptionParser with banner, separators, `--version`) is the correct approach. No changes to lib/ needed — this is a `bin/gpt_context.rb` enhancement.
+4. **Verify BUG-1** — Run `bin/jump.rb get <key>` live. If broken: find actual failure site. If fixed: write regression spec for `Jump::Config#find` round-trip and close.
+
+### Pre-Campaign Blockers: None
+
+Neither fix requires architectural changes. FR-2 is contained to `bin/gpt_context.rb`. The Jump verification is read-only unless the bug is confirmed.
+
+### What Agents Need to Know
+
+- Read `docs/planning/AGENTS.md` — test/lint patterns, commit format, quality gates
+- FR-2 spec: `docs/specs/fr-002-gpt-context-help-system.md`
+- gpt_context source: `lib/appydave/tools/gpt_context/` + `bin/gpt_context.rb`
+- Jump source: `lib/appydave/tools/jump/` (Config, Search, Commands/*)
+- Jump tests: `spec/appydave/tools/jump/` + `spec/support/jump_test_helpers.rb`
+- BUG-1 call chain: `CLI#run_get` → `Search#get` → `Config#find` → `locations.find { |loc| loc.key == key }`
+
+### Also Schedule Soon (from audit)
+
+- B016 — ManifestGenerator vs SyncFromSsd range string mismatch (data integrity — schedule next)
+- B017 — ssl_verify_peer: false in S3Operations (security — schedule next)
+- B018 — Jump Commands layer specs (no specs for Remove/Add/Update)
+
+### Mode Recommendation
+
+**Extend** — stack, patterns, and quality gates are known from prior campaigns. Use Extend, not Plan.

data/lib/appydave/tools/gpt_context/file_collector.rb

@@ -12,36 +12,29 @@ module Appydave
           @exclude_patterns = options.exclude_patterns
           @format = options.format
           @working_directory = File.expand_path(options.working_directory)
-          puts @working_directory
           @line_limit = options.line_limit
         end
 
         def build
-          FileUtils.cd(@working_directory) if @working_directory && Dir.exist?(@working_directory)
+          return build_formats unless @working_directory && Dir.exist?(@working_directory)
 
-          formats = @format.split(',')
-          result = formats.map do |fmt|
+          FileUtils.cd(@working_directory) { build_formats }
+        end
+
+        private
+
+        def build_formats
+          @format.split(',').map do |fmt|
             case fmt
-            when 'tree'
-              build_tree
-            when 'content'
-              build_content
-            when 'json'
-              build_json
-            when 'aider'
-              build_aider
-            else
-              ''
+            when 'tree'    then build_tree
+            when 'content' then build_content
+            when 'json'    then build_json
+            when 'aider'   then build_aider
+            else ''
             end
           end.join("\n\n")
-
-          FileUtils.cd(Dir.home) if @working_directory
-
-          result
         end
 
-        private
-
         def build_content
           concatenated_content = []
 

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.75.0'
+    VERSION = '0.76.0'
   end
 end

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "AppyDave YouTube Automation Tools",
   "scripts": {
     "release": "semantic-release"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.75.0
+  version: 0.76.0
 platform: ruby
 authors:
 - David Cruwys
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-08 00:00:00.000000000 Z
+date: 2026-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -295,6 +295,11 @@ files:
 - docs/guides/tools/video-file-namer.md
 - docs/guides/tools/youtube-automation.md
 - docs/guides/tools/youtube-manager.md
+- docs/planning/AGENTS.md
+- docs/planning/BACKLOG.md
+- docs/planning/fr2-gpt-context-help/AGENTS.md
+- docs/planning/fr2-gpt-context-help/IMPLEMENTATION_PLAN.md
+- docs/planning/next-round-brief.md
 - docs/specs/fr-002-gpt-context-help-system.md
 - docs/specs/fr-003-jump-location-tool.md
 - docs/specs/zsh-history-tool.md