appydave-tools 0.76.6 → 0.76.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4172ac86ad4f32c89534b2129ffed582137abc47e21fe1fb2e1d18c5a56608e
-  data.tar.gz: ed067098e65634fce56abf446313a7f58657dbc7fc45499915cb34d6a9ae5afe
+  metadata.gz: 837cfa631ce3f72655208add542964a605efa385aea01abfe49c55fb9110cdbb
+  data.tar.gz: 4adfd72dad7dc7a41f909857a21616d3385b259ee11969d94641c75731713924
 SHA512:
-  metadata.gz: 79f3caf203405a2cf7337da3129595433515c04e6b4f9f1203b70b5ef89e07caa07ac212d6e9bb85244185f5d5d3b8e20f175e01e7587fb1fe1920630dadf8e1
-  data.tar.gz: e42dfc787b1331d7fdfbd32c731f13e03f946bf5e2fa9d89f948f9cb59dc393a80e054b075b650d51d72eb7070f846f0253beef5e011cf3c632b8181b5b30f7f
+  metadata.gz: 2748e05e28b1c0cd4a7e6ec99f13a513c68ec49115d6b90bd0090d25467958eb0dd759cbf6fb8b94f210fc1835ee5d2c77cac79e3d7043cac2127513d982d89f
+  data.tar.gz: cf039ebec627c4899f5abc6c309829894c4dbca2ec71daf6ceb1143f61b72a46edb480223c9a8ab6acd5892ef343980f5395d6f6363276352056f111c3753026

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.76.7](https://github.com/appydave/appydave-tools/compare/v0.76.6...v0.76.7) (2026-03-19)
+
+
+### Bug Fixes
+
+* extract S3ArgParser module from VatCLI; add spec ([9bbd709](https://github.com/appydave/appydave-tools/commit/9bbd7099c26b774b68103f4d37d0a25f22f4abc2))
+
+## [0.76.6](https://github.com/appydave/appydave-tools/compare/v0.76.5...v0.76.6) (2026-03-19)
+
+
+### Bug Fixes
+
+* extract S3ScanCommand class from VatCLI; add smoke-test spec ([cd03606](https://github.com/appydave/appydave-tools/commit/cd03606e3307665c7f69391d6c160f50df1773ba))
+* remove redundant rubocop disable directives from S3ScanCommand (CI rubocop 1.85.1) ([4c9deb4](https://github.com/appydave/appydave-tools/commit/4c9deb4298d4577a99d0e82e7b72918a26275d40))
+
 ## [0.76.5](https://github.com/appydave/appydave-tools/compare/v0.76.4...v0.76.5) (2026-03-19)
 
 

data/bin/dam

@@ -154,7 +154,7 @@ class VatCLI
 
   # S3 Upload
   def s3_up_command(args)
-    options = parse_s3_args(args, 's3-up')
+    options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-up')
     s3_ops = Appydave::Tools::Dam::S3Operations.new(options[:brand], options[:project])
     s3_ops.upload(dry_run: options[:dry_run])
   rescue StandardError => e
@@ -164,7 +164,7 @@ class VatCLI
 
   # S3 Download
   def s3_down_command(args)
-    options = parse_s3_args(args, 's3-down')
+    options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-down')
     s3_ops = Appydave::Tools::Dam::S3Operations.new(options[:brand], options[:project])
     s3_ops.download(dry_run: options[:dry_run])
   rescue StandardError => e
@@ -174,7 +174,7 @@ class VatCLI
 
   # S3 Status
   def s3_status_command(args)
-    options = parse_s3_args(args, 's3-status')
+    options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-status')
     s3_ops = Appydave::Tools::Dam::S3Operations.new(options[:brand], options[:project])
     s3_ops.status
   rescue StandardError => e
@@ -184,7 +184,7 @@ class VatCLI
 
   # S3 Cleanup Remote
   def s3_cleanup_remote_command(args)
-    options = parse_s3_args(args, 's3-cleanup-remote')
+    options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-cleanup-remote')
     s3_ops = Appydave::Tools::Dam::S3Operations.new(options[:brand], options[:project])
     s3_ops.cleanup(force: options[:force], dry_run: options[:dry_run])
   rescue StandardError => e
@@ -194,7 +194,7 @@ class VatCLI
 
   # S3 Cleanup Local
   def s3_cleanup_local_command(args)
-    options = parse_s3_args(args, 's3-cleanup-local')
+    options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-cleanup-local')
     s3_ops = Appydave::Tools::Dam::S3Operations.new(options[:brand], options[:project])
     s3_ops.cleanup_local(force: options[:force], dry_run: options[:dry_run])
   rescue StandardError => e
@@ -204,7 +204,7 @@ class VatCLI
 
   # Share file via pre-signed URL
   def s3_share_command(args)
-    options = parse_share_args(args)
+    options = Appydave::Tools::Dam::S3ArgParser.parse_share(args)
 
     share_ops = Appydave::Tools::Dam::ShareOperations.new(options[:brand], options[:project])
     share_ops.generate_links(files: options[:file], expires: options[:expires], download: options[:download])
@@ -215,7 +215,7 @@ class VatCLI
 
   # Discover files in S3 for a project
   def s3_discover_command(args)
-    options = parse_discover_args(args)
+    options = Appydave::Tools::Dam::S3ArgParser.parse_discover(args)
     files = fetch_s3_files(options[:brand_key], options[:project_id])
 
     return if handle_empty_files?(files, options[:brand_key], options[:project_id])
@@ -228,7 +228,7 @@ class VatCLI
 
   # Archive project to SSD
   def archive_command(args)
-    options = parse_s3_args(args, 'archive')
+    options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 'archive')
     s3_ops = Appydave::Tools::Dam::S3Operations.new(options[:brand], options[:project])
     s3_ops.archive(force: options[:force], dry_run: options[:dry_run])
   rescue StandardError => e
@@ -461,132 +461,6 @@ class VatCLI
     exit 1
   end
 
-  # Parse S3 command arguments
-  # rubocop:disable Metrics/MethodLength
-  def parse_s3_args(args, command)
-    dry_run = args.include?('--dry-run')
-    force = args.include?('--force')
-    args = args.reject { |arg| arg.start_with?('--') }
-
-    brand_arg = args[0]
-    project_arg = args[1]
-
-    if brand_arg.nil?
-      # Auto-detect from PWD
-      brand, project_id = Appydave::Tools::Dam::ProjectResolver.detect_from_pwd
-      if brand.nil? || project_id.nil?
-        puts '❌ Could not auto-detect brand/project from current directory'
-        puts "Usage: dam #{command} <brand> <project> [--dry-run]"
-        exit 1
-      end
-      brand_key = brand # Already detected, use as-is
-    else
-      # Validate brand exists before trying to resolve project
-      unless valid_brand?(brand_arg)
-        puts "❌ Invalid brand: '#{brand_arg}'"
-        puts ''
-        puts 'Valid brands:'
-        puts '  appydave  → v-appydave         (AppyDave brand)'
-        puts '  voz       → v-voz              (VOZ client)'
-        puts '  aitldr    → v-aitldr           (AITLDR brand)'
-        puts '  kiros     → v-kiros            (Kiros client)'
-        puts '  joy       → v-beauty-and-joy   (Beauty & Joy)'
-        puts '  ss        → v-supportsignal    (SupportSignal)'
-        puts ''
-        puts "Usage: dam #{command} <brand> <project> [--dry-run]"
-        exit 1
-      end
-
-      brand_key = brand_arg # Use the shortcut/key (e.g., 'appydave')
-      brand = Appydave::Tools::Dam::Config.expand_brand(brand_arg) # Expand for path resolution
-      project_id = Appydave::Tools::Dam::ProjectResolver.resolve(brand_arg, project_arg)
-    end
-
-    # Set ENV for compatibility with ConfigLoader
-    ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand)
-
-    { brand: brand_key, project: project_id, dry_run: dry_run, force: force }
-  end
-  # rubocop:enable Metrics/MethodLength
-
-  def valid_brand?(brand_key)
-    Appydave::Tools::Configuration::Config.configure
-    brands = Appydave::Tools::Configuration::Config.brands
-    brands.key?(brand_key) || brands.shortcut?(brand_key)
-  end
-
-  def parse_share_args(args)
-    # Extract --expires flag
-    expires = '7d' # default
-    if (expires_index = args.index('--expires'))
-      expires = args[expires_index + 1]
-      args.delete_at(expires_index + 1)
-      args.delete_at(expires_index)
-    end
-
-    # Extract --download flag
-    download = args.include?('--download')
-
-    # Remove other flags
-    args = args.reject { |arg| arg.start_with?('--') }
-
-    brand_arg = args[0]
-    project_arg = args[1]
-    file_arg = args[2]
-
-    show_share_usage_and_exit if brand_arg.nil? || project_arg.nil? || file_arg.nil?
-
-    brand_key = brand_arg
-    brand = Appydave::Tools::Dam::Config.expand_brand(brand_arg)
-    project_id = Appydave::Tools::Dam::ProjectResolver.resolve(brand_arg, project_arg)
-
-    # Set ENV for compatibility with ConfigLoader
-    ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand)
-
-    { brand: brand_key, project: project_id, file: file_arg, expires: expires, download: download }
-  end
-
-  def show_share_usage_and_exit
-    puts 'Usage: dam s3-share <brand> <project> <file> [--expires 7d] [--download]'
-    puts ''
-    puts 'Options:'
-    puts '  --expires TIME    Expiry time (default: 7d)'
-    puts '  --download        Force download instead of viewing in browser'
-    puts ''
-    puts 'Examples:'
-    puts '  dam s3-share appydave b70 video.mp4'
-    puts '  dam s3-share appydave b70 video.mp4 --expires 24h'
-    puts '  dam s3-share appydave b70 video.mp4 --download'
-    puts '  dam s3-share voz boy-baker final-edit.mov --expires 3d --download'
-    exit 1
-  end
-
-  def parse_discover_args(args)
-    shareable = args.include?('--shareable')
-    args = args.reject { |arg| arg.start_with?('--') }
-
-    brand_arg = args[0]
-    project_arg = args[1]
-
-    if brand_arg.nil? || project_arg.nil?
-      puts 'Usage: dam s3-discover <brand> <project> [--shareable]'
-      puts ''
-      puts 'Examples:'
-      puts '  dam s3-discover appydave b70              # List files'
-      puts '  dam s3-discover appydave b70 --shareable  # Generate share commands'
-      exit 1
-    end
-
-    brand_key = brand_arg
-    brand = Appydave::Tools::Dam::Config.expand_brand(brand_arg)
-    project_id = Appydave::Tools::Dam::ProjectResolver.resolve(brand_arg, project_arg)
-
-    # Set ENV for compatibility with ConfigLoader
-    ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand)
-
-    { brand_key: brand_key, project_id: project_id, shareable: shareable }
-  end
-
   def fetch_s3_files(brand_key, project_id)
     s3_ops = Appydave::Tools::Dam::S3Operations.new(brand_key, project_id)
     s3_ops.list_s3_files

data/docs/planning/AGENTS.md

@@ -45,7 +45,7 @@ kfeat "add feature description"             # Minor version bump
 kfix "fix bug description"                  # Patch version bump
 ```
 
-**Baseline (2026-03-19):** 831 examples, 0 failures, ~85.92% line coverage
+**Baseline (2026-03-19):** 847 examples, 0 failures, ~86.21% line coverage
 
 ---
 
@@ -221,9 +221,9 @@ Appydave::Tools::Configuration::Config.configure
 
 ## Quality Gates
 
-- **Tests:** `bundle exec rspec` — 831 examples, 0 failures (do not ship if any fail)
+- **Tests:** `bundle exec rspec` — 847 examples, 0 failures (do not ship if any fail)
 - **Lint:** `bundle exec rubocop --format clang` — 0 offenses (CI will reject)
-- **Coverage:** ≥ 85.92% line coverage
+- **Coverage:** ≥ 86.21% line coverage
 - **frozen_string_literal:** Required on every new `.rb` file
 - **Commit format:** `kfeat`/`kfix` only — triggers semantic versioning + CI wait
 
@@ -248,6 +248,12 @@ Appydave::Tools::Configuration::Config.configure
 - **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 extract-vat-cli (2026-03-19)
+
+- **Do NOT carry over rubocop-disable comments when extracting methods.** Run rubocop on the new file first — methods that needed disables in a 1,600-line God class often don't exceed thresholds in a properly-scoped library class. Carrying them over causes CI to flag `Lint/RedundantCopDisableDirective` and requires a second fix commit.
+- **grep for callers before writing the plan.** `format_bytes` had 4 callers in bin/dam, not 3 as counted from memory. The orphaned-projects loop was missed.
+- **`valid_brand?` needs `Config.brands` mock, not just `SettingsConfig` mock.** The shared `'with vat filesystem and brands'` context only mocks `SettingsConfig#video_projects_root`. Any method calling `Config.brands` directly needs an explicit brands config mock.
+
 ### 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.

data/docs/planning/BACKLOG.md

@@ -1,7 +1,7 @@
 # Project Backlog — AppyDave Tools
 
-**Last updated**: 2026-03-19 (micro-cleanup campaign complete)
-**Total**: 33 | Pending: 7 | In Progress: 1 | Done: 25 | Deferred: 0 | Rejected: 0
+**Last updated**: 2026-03-19 (extract-vat-cli campaign complete)
+**Total**: 37 | Pending: 11 | Done: 26 | Deferred: 0 | Rejected: 0
 
 ---
 
@@ -14,8 +14,12 @@
 - [ ] 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) | Campaign: extract-vat-cli
+- [x] B011 — Arch: extract VatCLI business logic from bin/dam (1,600-line God class) | Completed: extract-vat-cli (2026-03-19)
 - [ ] B020 — Arch: split S3Operations (1,030 lines, mixed I/O + logic) | Priority: low
+- [ ] B034 — Fix: replace exit 1 with typed exceptions in S3ScanCommand + S3ArgParser | Priority: high (blocks B007 + test coverage)
+- [ ] B035 — Fix: remove ENV['BRAND_PATH'] side effect from S3ArgParser | Priority: high (blocks B007 parallelism)
+- [ ] B036 — Tests: improve S3ScanCommand spec from D to B (depends on B034) | Priority: medium
+- [ ] B037 — Tests: LocalSyncStatus :partial case, local_file_count assertion, Zone.Identifier exclusion | Priority: medium
 
 ---
 

data/docs/planning/extract-vat-cli/IMPLEMENTATION_PLAN.md

@@ -5,13 +5,13 @@
 **Target**: All 4 complete; 831+ examples passing; rubocop 0 offenses; no regressions
 
 ## Summary
-- Total: 4 | Complete: 0 | In Progress: 0 | Pending: 4 | Failed: 0
+- Total: 4 | Complete: 4 | In Progress: 0 | Pending: 0 | Failed: 0
 
 ## Pending
 - [x] extract-format-bytes — Replaced 4 callers (plan said 3; orphaned-projects loop in display_s3_scan_table was a 4th). format_bytes deleted. rubocop 0 offenses. Commit: 3cd362f.
 - [x] extract-local-sync-status — LocalSyncStatus module created, 7 specs added (838 total), both methods gone from VatCLI. Side-fix: restored youtube_automation_config require incorrectly removed in prior commit. v0.76.5.
-- [~] extract-s3-scan-command — Extract `scan_single_brand_s3` + `scan_all_brands_s3` + `display_s3_scan_table` → new `S3ScanCommand` class; add spec; **depends on extract-local-sync-status completing first**
-- [ ] extract-s3-arg-parser — Extract `parse_s3_args` + `valid_brand?` + `parse_share_args` + `show_share_usage_and_exit` + `parse_discover_args` → new `S3ArgParser` class; add spec
+- [x] extract-s3-scan-command — S3ScanCommand created, 2 smoke tests added (840 total), 3 methods gone from VatCLI. Note: rubocop-disable directives became redundant once methods left God class — needed 2nd kfix to remove them. v0.76.6.
+- [x] extract-s3-arg-parser — S3ArgParser module created, 7 specs added (847 total), 5 methods + 8 callers updated, all gone from VatCLI. Note: valid_brand? needed Config.brands mock (shared context only mocks SettingsConfig). v0.76.7.
 
 ## In Progress
 

data/docs/planning/extract-vat-cli/assessment.md

@@ -0,0 +1,107 @@
+# Assessment: extract-vat-cli
+
+**Campaign**: extract-vat-cli
+**Date**: 2026-03-19 → 2026-03-19
+**Results**: 4/4 complete, 0 failed
+
+---
+
+## Results Summary
+
+| Work Unit | Outcome | Version | Notes |
+|---|---|---|---|
+| extract-format-bytes | ✅ Complete | v0.76.4→ | 4 callers replaced (plan said 3; orphaned-projects loop was 4th) |
+| extract-local-sync-status | ✅ Complete | v0.76.5 | Side-fix: restored youtube_automation_config require removed in prior commit |
+| extract-s3-scan-command | ✅ Complete | v0.76.6 | Needed 2nd kfix: inherited rubocop-disable directives became redundant |
+| extract-s3-arg-parser | ✅ Complete | v0.76.7 | valid_brand? needed BrandsConfig mock; parse_share fully tested |
+
+**Suite:** 831 → 847 examples (+16), 0 failures, 86.21% coverage. rubocop 0 offenses. CI green on all 4 commits.
+
+---
+
+## What Worked Well
+
+1. **Sequential wave strategy was correct.** All 4 work units touched bin/dam — wave size = 1 was the only safe option. No conflicts, no merge issues, zero failed agents.
+
+2. **AGENTS.md quality was sufficient.** All agents executed cleanly without confusion about which methods to move or which callers to update. The detailed WU-specific instructions in the campaign AGENTS.md were the right level of specificity.
+
+3. **format_bytes extraction was genuinely trivial.** FileHelper.format_size already existed and was identical. WU1 was pure deletion + caller update — no logic risk.
+
+4. **LocalSyncStatus came out clean.** The module_function pattern worked correctly, the shared filesystem context covered most branches, and the side-fix of youtube_automation_config was a net win.
+
+5. **bin/dam went from 1,600 → 1,223 lines (−23%) and 20+ → 5 rubocop-disables.** The remaining 5 are structural (help text dispatch, not logic). Significant improvement.
+
+---
+
+## What Didn't Work
+
+1. **Inherited rubocop-disable directives caused 2nd kfix commits** (WU3, WU4). Methods that needed `Metrics/MethodLength` disable in the God class context don't exceed thresholds in properly-scoped library classes. CI rubocop 1.85.1 flags them as redundant. Rule: don't carry over rubocop-disable comments when extracting — run rubocop fresh on the new file.
+
+2. **Caller count was wrong in the plan.** Plan said 3 callers for format_bytes; there were 4 (orphaned-projects loop in display_s3_scan_table). This was a minor issue (caught and fixed by WU1 agent) but points to a planning discipline gap: grep for callers, don't count from memory.
+
+3. **exit 1 calls were carried into library code.** `S3ScanCommand` and `S3ArgParser` both call `exit 1` in response to invalid inputs. This was the pre-existing VatCLI pattern — the extraction was faithful — but it now lives in library classes where it's a boundary violation. Makes testing error paths impossible and blocks safe parallelism (B007).
+
+4. **S3ScanCommand spec is F-grade (confirmed by independent test audit).** Two `respond_to` tests confirm the class loads; nothing more. 90 lines of orchestration logic — manifest merging, orphan detection, LocalSyncStatus wiring — are completely unprotected. The `exit 1` call at line 55 makes the "no manifest" path untestable without production code changes first.
+
+5. **`Zone.Identifier` exclusion in LocalSyncStatus has no test.** The filter for Windows metadata files (line 26) is untested — removal or inversion would pass all current specs silently.
+
+6. **`ENV['BRAND_PATH']` side-effect never asserted in S3ArgParser spec.** All three parse methods set it; none of the specs check it. A key-name change would silently break ConfigLoader downstream.
+
+---
+
+## Key Learnings — Application
+
+1. **Don't carry over rubocop-disable comments when extracting.** Run rubocop fresh on the new file; only add disables if actually triggered.
+2. **grep for callers before writing the plan.** Don't count from memory or code review alone.
+3. **Library classes must not call `exit`.** Raise typed exceptions (`ConfigurationError`, `UsageError`) — let the CLI layer print and exit. Required before B007.
+4. **`valid_brand?` and anything calling `Config.brands` needs BrandsConfig mock** — the shared context only mocks `SettingsConfig#video_projects_root`.
+5. **ENV['BRAND_PATH'] side effect now in library code.** S3ArgParser sets a process-wide env var as a side effect of argument parsing. Must be resolved before parallelism (B007).
+
+---
+
+## Key Learnings — Ralph Loop
+
+1. **Wave size = 1 was correct for God-class extraction.** When all work units share a single target file, parallel waves cause conflicts. Plan for sequential from the start.
+2. **Detailed WU-specific AGENTS.md sections paid off.** Specifying exact line numbers, method names, and new class signatures eliminated agent confusion. Worth the upfront effort.
+3. **Side-fixes happen.** WU2 found and fixed a pre-existing require omission. Good — agents should fix what they find. Update the plan notes so the next session knows.
+4. **2nd kfix commits were needed on 2/4 work units** — predictable pattern for extractions. Build in a "check for redundant rubocop directives" step in future extraction AGENTS.md.
+
+---
+
+## Promote to Main KDD?
+
+- "Don't carry over rubocop-disable when extracting" → yes, promote
+- "grep for callers before planning" → yes, promote
+- "Library classes must not call exit" → yes, promote (already in project AGENTS.md, promote to KDD)
+
+---
+
+## Suggestions for Next Campaign
+
+### Debt introduced by this campaign (should address before B007)
+
+**B034 — Fix: replace `exit 1` with typed exceptions in S3ScanCommand + S3ArgParser**
+- `S3ScanCommand#scan_single` calls `exit 1` at line 55 (no manifest path)
+- `S3ArgParser` calls `exit 1` at 4 locations (invalid brand, PWD auto-detect fail, discover missing args, share missing args)
+- Fix: raise `Appydave::Tools::Dam::ConfigurationError` / new `UsageError` subclass
+- VatCLI `rescue StandardError` already handles these at command level
+- Unblocks proper testing of error paths AND safe parallelism
+
+**B035 — Fix: remove ENV['BRAND_PATH'] side effect from S3ArgParser**
+- `parse_s3`, `parse_share`, `parse_discover` all set `ENV['BRAND_PATH']` as a side effect
+- Acceptable in a single-process CLI; unsafe in parallel execution
+- Fix: return the brand_path in the result hash and let VatCLI set it, or extract to explicit `S3ArgParser.configure_env!(brand)`
+
+**B036 — Tests: improve S3ScanCommand spec from D to B**
+- Depends on B034 (exit → exception) — can't test "no manifest" path until that's fixed
+- Add: mocked S3Scanner + filesystem fixture, assert manifest merge logic, assert LocalSyncStatus wiring
+
+**B037 — Tests: add LocalSyncStatus :partial case + local_file_count assertion**
+- Add `:partial` context (1 file in staging, s3 has 3) — assert `:partial` status and `local_file_count: 1`
+- Add assertion that `:synced` case sets `local_file_count` correctly
+
+### Mode recommendation for next session
+
+**4. Extend** — these are small debt items, same stack, inherit this AGENTS.md.
+
+Or, if you want to move forward to B007 (parallelism) instead: address B034 + B035 first (1-wave campaign), then B007 becomes buildable.

data/docs/planning/extract-vat-cli/learnings/wave-learnings.md

@@ -0,0 +1,36 @@
+# Wave Learnings — extract-vat-cli
+
+**Campaign:** extract-vat-cli
+**Date:** 2026-03-19
+**Result:** 4/4 complete. 831 → 847 examples (+16). v0.76.3 → v0.76.7.
+
+---
+
+## Application Learnings
+
+### 1. format_bytes had 4 callers, not 3
+The orphaned-projects loop in `display_s3_scan_table` had its own `format_bytes` call. Plan said 3 callers; there were 4. Always grep for callers before writing the plan rather than counting from memory.
+
+### 2. rubocop-disable directives become redundant when methods leave God class
+WU3 and WU4 both needed a second `kfix` to remove `rubocop:disable Metrics/MethodLength` and `Metrics/CyclomaticComplexity` directives that were valid in the 1,600-line VatCLI context but flagged as redundant by CI rubocop 1.85.1 once the methods were in properly-scoped library classes.
+
+**Rule for future extractions:** Do NOT carry over rubocop-disable comments. Run rubocop locally on the new file first — only add disables if rubocop actually flags an offense.
+
+### 3. valid_brand? needed Config.brands mock, not just SettingsConfig mock
+The shared context `'with vat filesystem and brands'` only mocks `SettingsConfig#video_projects_root`. Testing `valid_brand?` (which calls `Config.brands`) required an explicit `Config.configure` + `Config.brands` mock with a test `BrandsConfig` instance. Document this in AGENTS.md for future S3ArgParser specs.
+
+### 4. youtube_automation_config require was missing (pre-existing)
+WU2 agent discovered that a prior `chore(cleanup)` commit had incorrectly removed `require 'appydave/tools/youtube_automation_config'` from `lib/appydave/tools.rb`. The CI was failing on a `NameError` for `YoutubeAutomationConfig` unrelated to our work. Agent restored it as a side-fix. This was confirmed pre-existing in WU1's CI output.
+
+---
+
+## Loop Meta-Learnings
+
+### Wave size = 1 was correct
+All 4 work units touched `bin/dam`. Sequential was the only safe option. No conflicts, no merge issues.
+
+### Agents produced clean rubocop output when not inheriting disables
+WU1 (no rubocop disables to inherit) was cleanest. WU2 produced clean output first-pass. WU3 and WU4 needed a second pass due to inherited directives — preventable with the "don't carry over disables" rule above.
+
+### 4 agents, all successful, no failures
+Every work unit completed in a single run (plus occasional second kfix for rubocop cleanup). AGENTS.md quality was sufficient — agents didn't get confused about which methods to move or which callers to update.