appydave-tools 0.76.11 → 0.76.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6557cf7bec5e564e6541cd1c65236f67888241cead0d9038be5bc57191c6dac4
-  data.tar.gz: 9e8b2ec379d9fb6d22a0437b980893ce031683da6ca2b2281b54b553f32323b8
+  metadata.gz: 9252ea22ead22d967de9096d645777ce4b65bc66e633fbf391e385e2719a839e
+  data.tar.gz: 4ea18017243a9d10dd8d0daedf060d91cf7a85fd95c3093d8e5fbeebbd7d82eb
 SHA512:
-  metadata.gz: 6aa1fd27da7b10e94594d0056fd001943bdce7b29b53d87173d6b0655880a58f2324f32f166719589f6b0585a1697a6c876a7335c197686feeaa07841b0f09a5
-  data.tar.gz: 8449913492bc836620632662c167de675488f10999af39e7f68b2d1b96fd4ddce4d52021ce60185ffc4e337656392bd92b46d579b7bbf443d40bec4c7f3600a6
+  metadata.gz: 863eb25208061bef821717a4b6fbf73159e299f7fc6e1fda7e79fc646ea849fe587574ed395b5d1c441238eb2bed781dd9154a5e69b4d0d27ae3c18f29fd7703
+  data.tar.gz: da1c86a72f91fa4bf8686e8c5ffb90916d84841cfc8b63189e2d7adafdb019a2c98223da79e0d1cab646c3da6a8e19182215eb2bcde23b4f517a0f1200e04db9

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.76.11](https://github.com/appydave/appydave-tools/compare/v0.76.10...v0.76.11) (2026-03-19)
+
+
+### Bug Fixes
+
+* use full BrandsConfig constant in s3_scan_command_spec to prevent CI verification failure ([3bd417d](https://github.com/appydave/appydave-tools/commit/3bd417d5d58dff89af736567ba7f85fd1d786fb6))
+
 ## [0.76.10](https://github.com/appydave/appydave-tools/compare/v0.76.9...v0.76.10) (2026-03-19)
 
 

data/bin/dam

@@ -155,7 +155,6 @@ class VatCLI
   # S3 Upload
   def s3_up_command(args)
     options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-up')
-    ENV['BRAND_PATH'] = options[:brand_path]
     s3_ops = Appydave::Tools::Dam::S3Operations.new(options[:brand], options[:project])
     s3_ops.upload(dry_run: options[:dry_run])
   rescue StandardError => e
@@ -166,7 +165,6 @@ class VatCLI
   # S3 Download
   def s3_down_command(args)
     options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-down')
-    ENV['BRAND_PATH'] = options[:brand_path]
     s3_ops = Appydave::Tools::Dam::S3Operations.new(options[:brand], options[:project])
     s3_ops.download(dry_run: options[:dry_run])
   rescue StandardError => e
@@ -177,7 +175,6 @@ class VatCLI
   # S3 Status
   def s3_status_command(args)
     options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-status')
-    ENV['BRAND_PATH'] = options[:brand_path]
     s3_ops = Appydave::Tools::Dam::S3Operations.new(options[:brand], options[:project])
     s3_ops.status
   rescue StandardError => e
@@ -188,7 +185,6 @@ class VatCLI
   # S3 Cleanup Remote
   def s3_cleanup_remote_command(args)
     options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-cleanup-remote')
-    ENV['BRAND_PATH'] = options[:brand_path]
     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
@@ -199,7 +195,6 @@ class VatCLI
   # S3 Cleanup Local
   def s3_cleanup_local_command(args)
     options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-cleanup-local')
-    ENV['BRAND_PATH'] = options[:brand_path]
     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
@@ -210,7 +205,6 @@ class VatCLI
   # Share file via pre-signed URL
   def s3_share_command(args)
     options = Appydave::Tools::Dam::S3ArgParser.parse_share(args)
-    ENV['BRAND_PATH'] = options[:brand_path]
     share_ops = Appydave::Tools::Dam::ShareOperations.new(options[:brand], options[:project])
     share_ops.generate_links(files: options[:file], expires: options[:expires], download: options[:download])
   rescue StandardError => e
@@ -221,7 +215,6 @@ class VatCLI
   # Discover files in S3 for a project
   def s3_discover_command(args)
     options = Appydave::Tools::Dam::S3ArgParser.parse_discover(args)
-    ENV['BRAND_PATH'] = options[:brand_path]
     files = fetch_s3_files(options[:brand_key], options[:project_id])
 
     return if handle_empty_files?(files, options[:brand_key], options[:project_id])
@@ -235,7 +228,6 @@ class VatCLI
   # Archive project to SSD
   def archive_command(args)
     options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 'archive')
-    ENV['BRAND_PATH'] = options[:brand_path]
     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
@@ -282,7 +274,6 @@ class VatCLI
 
   def generate_single_manifest(brand_arg, verbose: false)
     Appydave::Tools::Dam::Config.expand_brand(brand_arg)
-    ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand_arg)
 
     generator = Appydave::Tools::Dam::ManifestGenerator.new(brand_arg)
     generator.generate(verbose: verbose)
@@ -329,7 +320,6 @@ class VatCLI
     if brand_arg
       # Sync specific brand
       Appydave::Tools::Dam::Config.expand_brand(brand_arg)
-      ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand_arg)
 
       syncer = Appydave::Tools::Dam::SyncFromSsd.new(brand_arg)
       syncer.sync(dry_run: dry_run)

data/docs/planning/BACKLOG.md

@@ -1,7 +1,7 @@
 # Project Backlog — AppyDave Tools
 
-**Last updated**: 2026-03-19 (extract-vat-cli campaign complete)
-**Total**: 37 | Pending: 11 | Done: 26 | Deferred: 0 | Rejected: 0
+**Last updated**: 2026-03-19 (library-boundary-cleanup campaign complete)
+**Total**: 40 | Pending: 9 | Done: 30 | Deferred: 0 | Rejected: 0
 
 ---
 
@@ -10,16 +10,13 @@
 ### Medium Priority
 - [ ] B001 — FR-1: GPT Context token counting | Priority: medium
 - [ ] B012 — Arch: add integration tests for brand resolution end-to-end | Priority: medium
-- [ ] B007 — Performance: parallel git/S3 status checks for dam list | Priority: low
+- [ ] B007 — Performance: parallel git/S3 status checks for dam list | Priority: low (now unblocked)
 - [ ] 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
-- [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
+- [ ] B020 — Arch: split S3Operations (1,030 lines, mixed I/O + logic) | Priority: low (now unblocked)
+- [ ] B038 — Cleanup: remove ENV['BRAND_PATH'] dead code from bin/dam (10 assignments, never read in lib/) | Priority: low
+- [ ] B039 — Tests: strengthen s3_scan_command_spec data-value assertions + remove LocalSyncStatus stub | Priority: low
 
 ---
 
@@ -50,6 +47,11 @@
 - [x] B031 — Tests: add_spec `type` field assertion | Completed: already in commit 8eec40c; closed micro-cleanup (2026-03-19)
 - [x] B032 — Tests: cli_spec `-f json` subprocess test | Completed: micro-cleanup (2026-03-19), v0.76.4
 - [x] B033 — Fix: file_collector.rb return `''` when working_directory missing | Completed: already in commit 13d5f87; closed micro-cleanup (2026-03-19)
+- [x] B011 — Arch: extract VatCLI business logic from bin/dam (1,600-line God class) | Completed: extract-vat-cli (2026-03-19)
+- [x] B034 — Fix: replace exit 1 with typed exceptions in S3ScanCommand + S3ArgParser; add UsageError | Completed: library-boundary-cleanup (2026-03-19), v0.76.8
+- [x] B035 — Fix: remove ENV['BRAND_PATH'] side effect from S3ArgParser; return brand_path: in result hash | Completed: library-boundary-cleanup (2026-03-19), v0.76.9
+- [x] B036 — Tests: rebuild S3ScanCommand spec from D to B (10 behaviour examples) | Completed: library-boundary-cleanup (2026-03-19), v0.76.10
+- [x] B037 — Tests: LocalSyncStatus :partial, local_file_count, Zone.Identifier exclusion, unknown format | Completed: library-boundary-cleanup (2026-03-19), v0.76.11
 
 ---
 

data/docs/planning/env-dead-code-cleanup/AGENTS.md

@@ -0,0 +1,234 @@
+# AGENTS.md — AppyDave Tools / env-dead-code-cleanup campaign
+
+> Operational knowledge for every background agent. Self-contained — you receive only this file + your work unit prompt.
+> Inherited from: library-boundary-cleanup campaign (2026-03-20)
+> Updated for: env-dead-code-cleanup campaign (2026-03-20)
+
+---
+
+## 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 campaign:** env-dead-code-cleanup — remove confirmed dead ENV code and strengthen one test assertion.
+**Commits:** Always use `kfeat`/`kfix` — never `git commit` directly.
+
+---
+
+## ⚠️ Pre-Commit Check (Mandatory Every Commit)
+
+```bash
+git status
+```
+
+Confirm ONLY the files you intentionally changed are staged. **Stage by file name — never `git add .` or `git add -A`.**
+
+```bash
+# Correct:
+git add bin/dam
+kfix "..."
+
+# Wrong — stages everything including planning files:
+git add .
+```
+
+**Why:** Three prior campaigns have had accidental staging from `git add .`. It is the single most common failure mode in this repo.
+
+---
+
+## Build & Run Commands
+
+```bash
+eval "$(rbenv init -)"
+
+RUBYOPT="-W0" bundle exec rspec                              # Full suite
+bundle exec rspec spec/appydave/tools/dam/s3_scan_command_spec.rb  # Single file
+bundle exec rubocop --format clang                           # Lint (matches CI)
+
+kfeat "description"   # Minor version bump
+kfix "description"    # Patch version bump
+```
+
+**Baseline (start of env-dead-code-cleanup):** 861 examples, 0 failures, 86.43% line coverage
+
+---
+
+## Directory Structure
+
+```
+bin/
+  dam                           Main DAM CLI — target of B038 (10 ENV removals)
+lib/appydave/tools/dam/
+  errors.rb                     UsageError, ConfigurationError, etc.
+  s3_scan_command.rb            S3 scan orchestration
+  s3_arg_parser.rb              CLI arg parsing — ENV side-effect already removed
+  local_sync_status.rb          Local s3-staging sync status
+  manifest_generator.rb         ManifestGenerator — confirmed does NOT read ENV['BRAND_PATH']
+  sync_from_ssd.rb              SyncFromSsd — confirmed does NOT read ENV['BRAND_PATH']
+spec/
+  appydave/tools/dam/
+    s3_scan_command_spec.rb     Target of B039 (strengthen assertions)
+    local_sync_status_spec.rb   Already updated in library-boundary-cleanup
+```
+
+---
+
+## This Campaign
+
+### B038 — remove-env-dead-code
+
+**File:** `bin/dam` only.
+
+Remove all 10 `ENV['BRAND_PATH'] =` lines. Confirmed dead:
+- `grep -rn "BRAND_PATH" lib/ spec/` → 0 results
+- ManifestGenerator, SyncFromSsd: grep confirmed no reads
+
+**10 lines to delete** (line numbers approximate after prior edits — grep to find exact):
+
+| Method | Pattern to remove |
+|--------|------------------|
+| s3_up_command | `ENV['BRAND_PATH'] = options[:brand_path]` |
+| s3_down_command | `ENV['BRAND_PATH'] = options[:brand_path]` |
+| s3_status_command | `ENV['BRAND_PATH'] = options[:brand_path]` |
+| s3_cleanup_remote_command | `ENV['BRAND_PATH'] = options[:brand_path]` |
+| s3_cleanup_local_command | `ENV['BRAND_PATH'] = options[:brand_path]` |
+| s3_archive_command | `ENV['BRAND_PATH'] = options[:brand_path]` |
+| s3_share_command | `ENV['BRAND_PATH'] = options[:brand_path]` |
+| s3_discover_command | `ENV['BRAND_PATH'] = options[:brand_path]` |
+| generate_single_manifest | `ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand_arg)` |
+| sync_ssd_command | `ENV['BRAND_PATH'] = Appydave::Tools::Dam::Config.brand_path(brand_arg)` |
+
+After removing, also check if `options[:brand_path]` was the ONLY use of `options` in any method. If so, the `options =` assignment itself may now be unused. Grep the method body before removing.
+
+**Done when:**
+- `grep -n "BRAND_PATH" bin/dam` → 0 results
+- `RUBYOPT="-W0" bundle exec rspec` → 861 examples, 0 failures
+- `bundle exec rubocop --format clang` → 0 offenses
+- `git status` clean (only bin/dam staged)
+
+**Commit:** `kfix "remove ENV BRAND_PATH dead code from bin/dam (10 assignments, never read in lib)"`
+
+---
+
+### B039 — strengthen-s3-scan-spec
+
+**File:** `spec/appydave/tools/dam/s3_scan_command_spec.rb` only.
+
+**Read the current spec file in full before making any changes.**
+
+Two specific improvements:
+
+**1. Replace `not_to be_empty` with field-value assertion**
+
+Find the test that checks `project[:storage][:s3]` and replace the weak emptiness check:
+```ruby
+# Before (weak):
+expect(project[:storage][:s3]).not_to be_empty
+
+# After (catches wrong values):
+expect(project[:storage][:s3]).to include(
+  file_count: 3,
+  total_bytes: 1_500_000,
+  last_modified: '2025-01-01T00:00:00Z'
+)
+```
+
+Match the values to whatever the mock `scan_all_projects` returns in that context.
+
+**2. Remove LocalSyncStatus stub, let integration run**
+
+Find:
+```ruby
+allow(Appydave::Tools::Dam::LocalSyncStatus).to receive(:enrich!)
+```
+
+Remove this line. `LocalSyncStatus.enrich!` uses the filesystem — it needs the s3-staging directory to exist (or it sets `:no_project`/:no_files`). The test doesn't need to assert on `:local_status` — just ensure it doesn't raise.
+
+If removing the stub causes failures because LocalSyncStatus can't find the brand path, add an `s3-staging` folder to the fixture:
+```ruby
+FileUtils.mkdir_p(File.join(appydave_path, 'b65-test-project', 's3-staging'))
+```
+
+**Done when:**
+- `bundle exec rspec spec/appydave/tools/dam/s3_scan_command_spec.rb` → all pass
+- `RUBYOPT="-W0" bundle exec rspec` → 861 examples, 0 failures (count unchanged — no new specs)
+- `bundle exec rubocop --format clang` → 0 offenses
+- `git status` clean (only spec file staged)
+
+**Commit:** `kfix "strengthen s3_scan_command_spec field assertions; remove LocalSyncStatus stub"`
+
+---
+
+## Success Criteria (Every Work Unit)
+
+- [ ] `RUBYOPT="-W0" bundle exec rspec` — 861+ examples, 0 failures
+- [ ] `bundle exec rubocop --format clang` — 0 offenses
+- [ ] Line coverage ≥ 86.43%
+- [ ] `git status` clean, specific files staged (NOT `git add .`)
+
+---
+
+## Reference Patterns
+
+### Shared Context for DAM Specs
+
+```ruby
+RSpec.describe Appydave::Tools::Dam::SomeClass do
+  include_context 'with vat filesystem and brands', brands: %w[appydave voz]
+  # Provides: temp_folder, projects_root, appydave_path, voz_path
+  # SettingsConfig#video_projects_root mocked to return projects_root
+end
+```
+
+### instance_double — Always Use Full Constant
+
+```ruby
+# Correct:
+instance_double(Appydave::Tools::Configuration::Models::BrandsConfig)
+
+# Wrong — fails CI on Ubuntu:
+instance_double('BrandsConfig')
+```
+
+### Typed Exception Pattern
+
+```ruby
+raise Appydave::Tools::Dam::ConfigurationError, 'Manifest not found: /path'
+raise Appydave::Tools::Dam::UsageError, 'Usage: dam s3-up <brand> <project>'
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ `git add .` or `git add -A` — always stage specific files by name
+- ❌ `exit 1` in library code — use typed exceptions (already fixed in library-boundary-cleanup)
+- ❌ `ENV['BRAND_PATH'] =` in any file — confirmed dead, being removed in B038
+- ❌ `instance_double('StringForm')` — use full constant always
+- ❌ Inline brand transformations — use BrandResolver
+- ❌ Multiple `before` blocks in same RSpec context — merge them (RSpec/ScatteredSetup)
+- ❌ `$?` for subprocess status — use `$CHILD_STATUS`
+
+---
+
+## Learnings
+
+### From library-boundary-cleanup (2026-03-20)
+
+- **`instance_double` string form fails CI on Ubuntu.** Always use full constant: `instance_double(Fully::Qualified::ClassName)`.
+- **`git add .` is the recurring staging bug.** Stage specific files by name. Always. Every commit.
+- **`ENV['BRAND_PATH']` in bin/dam is dead code.** 10 assignments, 0 reads. Being removed in B038.
+- **VatCLI rescue blocks catch DamError correctly.** `UsageError < DamError < StandardError` — all 17 rescue blocks catch it without modification.
+
+### From extract-vat-cli (2026-03-19)
+
+- **Dirty working tree + kfix = accidental staging.** Run `git status` before every commit.
+- **rubocop-disable directives become redundant when methods move.** Check for orphaned disable/enable pairs after extraction.
+- **valid_brand? needs Config.brands mock.** Shared filesystem context only mocks SettingsConfig; Config.brands needs a separate mock.
+- **S3ScanCommand#scan_all already rescues per-brand.** Per-brand exceptions are isolated by design.
+
+### From DAM Enhancement Sprint (Jan 2025)
+
+- **BrandResolver is the critical path.** All dam commands flow through it.
+- **`Config.configure` is memoized but called redundantly.** Don't add new calls.
+- **Table format() pattern is non-obvious.** Headers misaligned 3× in UAT. Always verify with real data.

data/docs/planning/env-dead-code-cleanup/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,51 @@
+# IMPLEMENTATION_PLAN.md — env-dead-code-cleanup
+
+**Goal**: Remove confirmed dead code (10× `ENV['BRAND_PATH']` in bin/dam) and strengthen s3_scan_command_spec data-value assertions. Closes B038 + B039 from the library-boundary-cleanup audit.
+**Started**: 2026-03-20
+**Target**: Both items complete; 861+ examples passing; rubocop 0 offenses; no regressions
+
+## Summary
+- Total: 2 | Complete: 0 | In Progress: 2 | Pending: 0 | Failed: 0
+
+## Pending
+
+## In Progress
+- [~] B038 — remove-env-dead-code — Remove all 10 `ENV['BRAND_PATH'] =` assignments from bin/dam
+- [~] B039 — strengthen-s3-scan-spec — Replace `not_to be_empty` with field-value assertions; remove LocalSyncStatus stub
+
+## Complete
+
+## Failed / Needs Retry
+
+## Notes & Decisions
+
+### Wave Plan
+
+**Wave 1 — B038 + B039 in parallel**
+- B038 touches `bin/dam` only
+- B039 touches `spec/appydave/tools/dam/s3_scan_command_spec.rb` only
+- No shared files — safe to run in parallel
+
+### B038: All 10 ENV assignments confirmed dead (2026-03-20)
+
+| Line | Method | Form |
+|------|--------|------|
+| 158 | s3_up_command | `options[:brand_path]` |
+| 169 | s3_down_command | `options[:brand_path]` |
+| 180 | s3_status_command | `options[:brand_path]` |
+| 191 | s3_cleanup_remote_command | `options[:brand_path]` |
+| 202 | s3_cleanup_local_command | `options[:brand_path]` |
+| 213 | s3_archive_command | `options[:brand_path]` |
+| 224 | s3_share_command | `options[:brand_path]` |
+| 238 | s3_discover_command | `options[:brand_path]` |
+| 285 | generate_single_manifest | `Config.brand_path(brand_arg)` |
+| 332 | sync_ssd_command | `Config.brand_path(brand_arg)` |
+
+- `grep -rn "BRAND_PATH" lib/ spec/` → 0 results (confirmed 2026-03-20)
+- ManifestGenerator and SyncFromSsd do not read ENV['BRAND_PATH'] (confirmed 2026-03-20)
+
+### B039: What to strengthen in s3_scan_command_spec
+
+- Replace `expect(project[:storage][:s3]).not_to be_empty` with `include(file_count: 3, total_bytes: 1_500_000)`
+- Remove `allow(Appydave::Tools::Dam::LocalSyncStatus).to receive(:enrich!)` stub — let it run for real
+- If LocalSyncStatus.enrich! needs the s3-staging path to exist, create it in the fixture setup

data/docs/planning/library-boundary-cleanup/AGENTS.md

@@ -645,6 +645,12 @@ end
 - **`ENV['BRAND_PATH']` is set in 5 places in bin/dam.** Three are in parse methods (being extracted to B035). Two remain in `generate_single_manifest` and `sync_ssd_command` — out of scope for this campaign.
 - **Do NOT attempt B020 (split S3Operations) in this campaign.** Different class, different risk profile.
 
+### From library-boundary-cleanup (2026-03-20)
+
+- **`instance_double` string form fails CI on Ubuntu.** Always use full constant: `instance_double(Fully::Qualified::ClassName)`. String form passes locally but Ubuntu CI enforces constant lookup. A CI failure after a green local run is almost always this.
+- **`git add .` is the recurring staging bug.** Three campaigns have had accidental staging from `git add .`. Stage specific files by name: `git add lib/appydave/tools/dam/local_sync_status.rb spec/...`. Never `git add .` or `git add -A` in this repo.
+- **`ENV['BRAND_PATH']` in bin/dam is dead code.** 10 assignments in bin/dam, 0 reads in lib/. S3Operations receives brand_path as a constructor parameter. Tracked as B038 for cleanup.
+
 ### From extract-vat-cli (2026-03-19)
 
 - **valid_brand? needs Config.brands mock.** The shared filesystem context only mocks `SettingsConfig`. When testing code that calls `Config.brands`, mock it separately: `allow(Appydave::Tools::Configuration::Config).to receive(:brands).and_return(...)`.

data/docs/planning/library-boundary-cleanup/IMPLEMENTATION_PLAN.md

@@ -5,13 +5,13 @@
 **Target**: 4 items complete; 847+ examples passing; rubocop 0 offenses; no regressions
 
 ## Summary
-- Total: 4 | Complete: 3 | In Progress: 1 | Pending: 0 | Failed: 0
+- Total: 4 | Complete: 4 | In Progress: 0 | Pending: 0 | Failed: 0
 
 ## Pending
 
 ## In Progress
 - [x] B036 — tests-s3-scan-command — 10 behaviour examples replacing 2 smoke tests (happy path, manifest missing, empty results, orphaned projects, scan_all partial). 861 examples, 0 failures. 86.43% coverage. v0.76.10. Commit: de9d118.
-- [~] B037 — tests-local-sync-status — Add :partial case, local_file_count assertion, Zone.Identifier exclusion, unknown format guard
+- [x] B037 — tests-local-sync-status — 6 new examples: :partial (2), local_file_count in :synced (1), Zone.Identifier exclusion (2), unknown format guard (1). Source already had both features — tests only. CI fix: replaced string instance_double with full constant. v0.76.11. Commits: 3fddeff, 3bd417d.
 
 ## Complete
 - [x] B034 — extract-exit-calls — UsageError added to errors.rb; exit 1 replaced in s3_scan_command.rb (1) and s3_arg_parser.rb (4); show_share_usage_and_exit renamed. 847 examples, 0 failures. v0.76.8. Commit: 87bb43a.

data/docs/planning/library-boundary-cleanup/assessment.md

@@ -0,0 +1,109 @@
+# Assessment: library-boundary-cleanup
+
+**Campaign**: library-boundary-cleanup
+**Date**: 2026-03-19 → 2026-03-19
+**Results**: 4 complete, 0 failed
+**Final version**: v0.76.11 (from v0.76.7 baseline)
+**Quality audits**: code-quality-audit ✅ | test-quality-audit ✅
+
+---
+
+## Results Summary
+
+| Work Unit | Description | Result | Version |
+|-----------|-------------|--------|---------|
+| B034 | extract-exit-calls | ✅ Complete | v0.76.8 |
+| B035 | extract-env-side-effect | ✅ Complete | v0.76.9 |
+| B036 | tests-s3-scan-command | ✅ Complete | v0.76.10 |
+| B037 | tests-local-sync-status | ✅ Complete | v0.76.11 |
+
+**Test baseline:** 847 → 861+ examples (net +14), 0 failures, 86.43% line coverage
+
+---
+
+## What Worked Well
+
+1. **Wave plan held perfectly.** B034 → B035 → B036+B037 (parallel) ran with zero merge conflicts. Pre-reading the files before planning meant the sequencing constraints were exact.
+
+2. **B035 rubocop self-corrected.** Agent caught a `Lint/UselessAssignment` for the now-redundant `brand =` local variable that was only there to support the ENV assignment. Removed cleanly in the same commit.
+
+3. **LocalSyncStatus source already had the hard bits.** Zone.Identifier exclusion and `format` else-branch were already implemented — B037 only needed tests. Pre-reading confirmed this before writing any spec code.
+
+4. **VatCLI rescue chain worked exactly as predicted.** No rescue changes needed in bin/dam — `UsageError < DamError < StandardError` was caught by all 17 existing `rescue StandardError` blocks.
+
+5. **Code quality audit grade: HIGH.** 0 rubocop offenses, exception messages are actionable, ENV pattern in bin/dam is consistent across all 8 sites.
+
+---
+
+## What Didn't Work
+
+1. **B037 agent used `git add .` instead of staging specific files.** Accidentally included the B036 spec and IMPLEMENTATION_PLAN.md in its commit. Required a follow-up fix commit. (Recurring issue — pre-commit check needs to be more prominent in AGENTS.md.)
+
+2. **B036 CI failure on Ubuntu.** `instance_double('BrandsConfig')` (string form) failed double verification in CI but passed locally. Required a second `kfix` commit to replace with full constant `instance_double(Appydave::Tools::Configuration::Models::BrandsConfig)`. Ubuntu CI is stricter about constant resolution in instance_doubles.
+
+3. **ENV['BRAND_PATH'] is dead code.** The 10 `ENV['BRAND_PATH'] =` assignments in bin/dam (8 new from B035, 2 pre-existing) are never read anywhere in `lib/`. S3Operations receives `brand_path` as a constructor parameter. The ENV assignments preserved the original behaviour faithfully but the env var itself appears unused. Should be investigated and removed in a future cleanup.
+
+---
+
+## Key Learnings — Application
+
+1. **`instance_double` string form fails CI on Ubuntu.** Always use full constant form: `instance_double(Fully::Qualified::ClassName)`. The string form passes locally (RSpec doesn't resolve it) but Ubuntu CI enforces constant lookup.
+
+2. **`git add .` is the recurring staging bug.** Three campaigns now have had accidental staging from `git add .`. The AGENTS.md pre-commit rule needs to be in a more prominent position — not buried at the top, but repeated immediately before the commit step.
+
+3. **`ENV['BRAND_PATH']` may be vestigial.** Check whether any external consumers (config_loader, shell scripts, `.video-tools.env` loading) depend on it before removing. If confirmed unused: clean up the 10 assignments in bin/dam.
+
+4. **Read source before writing tests.** B037 avoided writing a Zone.Identifier exclusion to the source (it was already there) because AGENTS.md said to read the source first. Saved one unnecessary commit.
+
+---
+
+## Key Learnings — Ralph Loop
+
+1. **Extend mode is fast when the brief is complete.** The next-round-brief had exact file line numbers, precise changes, and confirmed dependency order. Planning took minutes, not a full session.
+
+2. **Wave 3 parallel worked cleanly.** B036 and B037 touched different spec files with no shared state. Both committed independently with no conflicts. The wave 3 parallel pattern is reliable for spec-only work.
+
+3. **Quality audit found real things.** ENV dead code finding and the B-grade test gaps (data-value assertions, LocalSyncStatus integration stub) are both actionable. Running audits before assessment is the right order.
+
+---
+
+## Code Quality Audit Findings
+
+**Grade: HIGH / Production-ready**
+
+- Exception hierarchy correct (`UsageError < DamError < StandardError`)
+- Exception messages user-friendly and actionable with recovery steps
+- ENV['BRAND_PATH'] pattern in VatCLI is consistent across all 8 call sites
+- 0 rubocop offenses
+- **One finding:** `ENV['BRAND_PATH']` set in 10 locations in bin/dam but never read in lib/ — dead code, low risk, cleanup candidate
+
+---
+
+## Test Quality Audit Findings
+
+**Grade: B (80% regression catch rate)**
+
+**s3_scan_command_spec — Grade B-:**
+- Manifest file write verified via real I/O ✅
+- Missing manifest raises ConfigurationError ✅
+- Empty S3 results handled gracefully ✅
+- Weakness: data-value assertions only check non-empty, not specific field values
+- Weakness: LocalSyncStatus mocked in scan_single tests — integration gap
+
+**local_sync_status_spec — Grade A-:**
+- Zone.Identifier exclusion test is strong (real files, would catch regression) ✅
+- All 4 status transitions tested ✅
+- format method covers all branches ✅
+- Weakness: nested directory traversal not tested; local_file_count = 0 edge case
+
+---
+
+## Suggestions for Next Campaign
+
+1. **Promote to BACKLOG:** `ENV['BRAND_PATH']` dead code cleanup — verify no consumers, then remove 10 assignments from bin/dam (1 work unit, low risk)
+
+2. **Promote to BACKLOG:** Strengthen s3_scan_command_spec data-value assertions + remove LocalSyncStatus stub to test integration (could fold into B020 S3Operations split campaign)
+
+3. **AGENTS.md update for next campaign:** Add `instance_double` rule ("always use full constant, never string form"). Move pre-commit `git status` check to a repeated callout immediately before commit instructions.
+
+4. **Next logical work:** B007 (parallel git/S3 status checks) and B020 (split S3Operations) are now unblocked — library boundaries are clean.

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.76.11'
+    VERSION = '0.76.12'
   end
 end

data/package.json

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.76.11
+  version: 0.76.12
 platform: ruby
 authors:
 - David Cruwys
@@ -300,6 +300,8 @@ files:
 - docs/planning/bugfix-and-security/AGENTS.md
 - docs/planning/bugfix-and-security/IMPLEMENTATION_PLAN.md
 - docs/planning/bugfix-and-security/assessment.md
+- docs/planning/env-dead-code-cleanup/AGENTS.md
+- docs/planning/env-dead-code-cleanup/IMPLEMENTATION_PLAN.md
 - docs/planning/extract-vat-cli/AGENTS.md
 - docs/planning/extract-vat-cli/IMPLEMENTATION_PLAN.md
 - docs/planning/extract-vat-cli/assessment.md
@@ -312,6 +314,7 @@ files:
 - docs/planning/fr2-gpt-context-help/assessment.md
 - docs/planning/library-boundary-cleanup/AGENTS.md
 - docs/planning/library-boundary-cleanup/IMPLEMENTATION_PLAN.md
+- docs/planning/library-boundary-cleanup/assessment.md
 - docs/planning/micro-cleanup/AGENTS.md
 - docs/planning/micro-cleanup/IMPLEMENTATION_PLAN.md
 - docs/planning/micro-cleanup/assessment.md