appydave-tools 0.76.13 → 0.76.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6081f58b2bf40e25bf4509d591368c361dc00957e924683d3f2179fe3fbc8d10
-  data.tar.gz: 44c1d63cc7558d323a735009876cb6bebd87c9117cf18a7b5eb25047eeff0d83
+  metadata.gz: 2c6c57202f05dffc3f46f1d929522ed55200a85d91ac427d831a2c9e77558693
+  data.tar.gz: ec9250e733a5ec31bef797f83c24c77f535e3ac9753954cab7f6e45c66bf7fca
 SHA512:
-  metadata.gz: 4d10e99fe30a5c09e803560904896abc0355d696a5b70d859acdeb0b2ca1e572502c85a99bf32a1f9f968e3544017d085b482284013e5b337155781d1b7cb13a
-  data.tar.gz: d08c8d573a35bf36bdebd3c9106359eb37d2bf5efb69a167a7db005e8340f05443c8b2e7bfc195a2639e4337d1beef79dca45b263ce65f16b73081cce1b900bb
+  metadata.gz: 933c28cc9392d407254f320529e3c6166648579794fa1b13fb2fc956bebc4900ccf4048eb97f3230a40ebee2d1ebce45b5588effebb5a05fe3c5e516270655d0
+  data.tar.gz: 381302acfc146d12aed9ebb5ee1e9e26de4b0d7c111e2b0c7883e4936bb4b5673e33617ec1c49fc515e89ad2d088acb7a583cc6ed862e946d0265160b917d30a

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.76.13](https://github.com/appydave/appydave-tools/compare/v0.76.12...v0.76.13) (2026-03-19)
+
+
+### Bug Fixes
+
+* remove redundant smoke-test from s3_scan_command_spec; fix RSpec/RepeatedExample CI rubocop offense ([5711e4e](https://github.com/appydave/appydave-tools/commit/5711e4e62d6ab648fc2a93fae32453095a00d4ca))
+
 ## [0.76.12](https://github.com/appydave/appydave-tools/compare/v0.76.11...v0.76.12) (2026-03-19)
 
 

data/docs/planning/BACKLOG.md

@@ -1,7 +1,7 @@
 # Project Backlog — AppyDave Tools
 
-**Last updated**: 2026-03-19 (library-boundary-cleanup campaign complete)
-**Total**: 40 | Pending: 9 | Done: 30 | Deferred: 0 | Rejected: 0
+**Last updated**: 2026-03-20 (env-dead-code-cleanup campaign complete)
+**Total**: 40 | Pending: 7 | Done: 32 | Deferred: 0 | Rejected: 0
 
 ---
 
@@ -15,8 +15,6 @@
 - [ ] B009 — UX: progress indicators for dam operations > 5s | Priority: low
 - [ ] B010 — UX: auto-adjust dam table column widths to terminal width | Priority: low
 - [ ] 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
 
 ---
 
@@ -52,6 +50,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
+- [x] B038 — Cleanup: remove ENV['BRAND_PATH'] dead code from bin/dam (10 assignments) | Completed: env-dead-code-cleanup (2026-03-20), v0.76.13
+- [x] B039 — Tests: strengthen s3_scan_command_spec field assertions + remove LocalSyncStatus stub | Completed: env-dead-code-cleanup (2026-03-20), v0.76.12
 
 ---
 

data/docs/planning/batch-a-features/AGENTS.md

@@ -0,0 +1,408 @@
+# AGENTS.md — AppyDave Tools / batch-a-features campaign
+
+> Self-contained operational knowledge. You receive only this file + your work unit prompt.
+> Inherited from: env-dead-code-cleanup (2026-03-20)
+
+---
+
+## Project Overview
+
+**Stack:** Ruby 3.4.2, Bundler 2.6.2, RSpec, RuboCop, semantic-release CI/CD.
+**Baseline:** 860 examples, 0 failures, 86.44% line coverage, v0.76.13
+**Commits:** `kfeat "message"` for new features (minor bump), `kfix "message"` for fixes (patch bump). Never `git commit` directly.
+
+---
+
+## ⚠️ kfix/kfeat Staging Behaviour
+
+`kfix` and `kfeat` run `git add .` internally — they stage EVERYTHING in the working tree.
+
+**Before calling kfix/kfeat:**
+```bash
+git status    # confirm ONLY your intended files are modified
+git diff      # review the actual changes
+```
+
+If unintended files appear:
+```bash
+git stash -- path/to/unintended/file    # stash specific file
+git checkout -- path/to/file            # discard unintended change
+```
+
+Then call kfix/kfeat once the tree is clean.
+
+---
+
+## Build & Run Commands
+
+```bash
+eval "$(rbenv init -)"
+
+RUBYOPT="-W0" bundle exec rspec                    # Full suite (860 examples baseline)
+bundle exec rspec spec/path/to/file_spec.rb        # Single file
+bundle exec rubocop --format clang                 # Lint (must be 0 offenses)
+
+kfeat "add feature description"    # new feature — minor version bump
+kfix "fix description"             # fix/improvement — patch version bump
+```
+
+---
+
+## Directory Structure
+
+```
+bin/
+  gpt_context.rb              GPT context CLI — target of B001
+  dam                         DAM CLI (VatCLI) — target of B009
+lib/appydave/tools/
+  gpt_context/
+    options.rb                Options struct — add show_tokens field (B001)
+    file_collector.rb         Builds content string from glob patterns
+    output_handler.rb         Writes content to clipboard/file
+  dam/
+    project_listing.rb        Table display for dam list — target of B010
+    brand_resolver.rb         Brand name transforms (appydave ↔ v-appydave)
+    config.rb                 Brand path resolution
+    project_resolver.rb       Project name resolution
+spec/
+  appydave/tools/dam/
+    brand_resolution_integration_spec.rb   NEW — target of B012
+  support/
+    dam_filesystem_helpers.rb              Shared context for DAM specs
+```
+
+---
+
+## B001 — gpt-context-token-counting
+
+**Files:** `lib/appydave/tools/gpt_context/options.rb`, `bin/gpt_context.rb`
+
+### What to build
+
+Add a `--tokens` / `-t` flag. When set, after collecting content, print an estimated token count to `$stderr` (so it doesn't pollute the content going to clipboard/file).
+
+**Token estimation:** `(content.length / 4.0).ceil` — industry-standard approximation for English/code (4 chars ≈ 1 token).
+
+### Step 1 — options.rb
+
+Add `show_tokens` to the Struct:
+```ruby
+Options = Struct.new(
+  :include_patterns,
+  :exclude_patterns,
+  :format,
+  :line_limit,
+  :debug,
+  :output_target,
+  :working_directory,
+  :prompt,
+  :show_tokens,         # ADD THIS
+  keyword_init: true
+) do
+  def initialize(**args)
+    super
+    # existing defaults...
+    self.show_tokens ||= false    # ADD THIS
+  end
+end
+```
+
+### Step 2 — bin/gpt_context.rb
+
+Add the CLI flag (after the `-p` option block, before the separator):
+```ruby
+opts.on('-t', '--tokens', 'Show estimated token count after collecting context') do
+  options.show_tokens = true
+end
+```
+
+After `content = gatherer.build` and before `output_handler = ...`, add:
+```ruby
+if options.show_tokens
+  token_estimate = (content.length / 4.0).ceil
+  char_count = content.length
+  $stderr.puts ''
+  $stderr.puts '── Token Estimate ──────────────────────────'
+  $stderr.puts "  Characters : #{char_count.to_s.rjust(10)}"
+  $stderr.puts "  Tokens (~4c): #{token_estimate.to_s.rjust(10)}"
+  $stderr.puts ''
+  if token_estimate > 200_000
+    $stderr.puts '  ⚠️  WARNING: Exceeds 200k tokens — may not fit most LLM context windows'
+  elsif token_estimate > 100_000
+    $stderr.puts '  ⚠️  NOTICE: Exceeds 100k tokens — check your LLM context limit'
+  end
+  $stderr.puts '────────────────────────────────────────────'
+  $stderr.puts ''
+end
+```
+
+### Done when B001 is complete
+- `bundle exec rspec spec/appydave/tools/gpt_context/` → all pass
+- Check if options_spec.rb needs a new example for `show_tokens` default — add one if it tests other defaults
+- `bundle exec rubocop --format clang` → 0 offenses
+- `RUBYOPT="-W0" bundle exec rspec` → 860+ examples, 0 failures
+- Commit: `kfeat "add --tokens flag to gpt_context for estimated token count output"`
+
+---
+
+## B009 — dam-progress-indicators
+
+**File:** `bin/dam` only.
+
+### What to build
+
+Add human-readable progress messages before and after long-running S3 operations. These operations can take 30s–5min with no feedback currently.
+
+### Commands to update
+
+**s3_up_command** — wrap the upload:
+```ruby
+def s3_up_command(args)
+  options = Appydave::Tools::Dam::S3ArgParser.parse_s3(args, 's3-up')
+  s3_ops = Appydave::Tools::Dam::S3Operations.new(options[:brand], options[:project])
+  verb = options[:dry_run] ? '🔍 Dry run:' : '⬆️  Uploading'
+  puts "#{verb} #{options[:project]} (#{options[:brand]}) → S3..."
+  s3_ops.upload(dry_run: options[:dry_run])
+rescue StandardError => e
+  # existing rescue
+end
+```
+
+**s3_down_command:**
+```ruby
+puts "⬇️  Downloading #{options[:project]} (#{options[:brand]}) from S3..."
+```
+
+**s3_status_command:**
+```ruby
+puts "🔍 Checking S3 status for #{options[:project]} (#{options[:brand]})..."
+```
+
+**archive_command:**
+```ruby
+puts "📦 Archiving #{options[:project]} (#{options[:brand]}) to SSD..."
+```
+
+**sync_ssd_command** (brand-level, not project):
+```ruby
+puts "🔄 Syncing #{brand_arg} from SSD..."
+```
+
+Read `bin/dam` carefully to find the exact method structure and rescue blocks before making changes. Add the `puts` line immediately after the `options =` assignment and before the `s3_ops =` instantiation.
+
+### Done when B009 is complete
+- `RUBYOPT="-W0" bundle exec rspec` → 860 examples, 0 failures (no new specs — bin/dam is untested by spec)
+- `bundle exec rubocop --format clang` → 0 offenses
+- Commit: `kfix "add progress indicators to dam S3 commands"`
+
+---
+
+## B010 — dam-column-widths
+
+**File:** `lib/appydave/tools/dam/project_listing.rb` only.
+
+### What to build
+
+Replace hardcoded separator line lengths with terminal-width detection. Also add path truncation for the PATH column.
+
+### Step 1 — add terminal_width helper
+
+Add a private class method:
+```ruby
+def self.terminal_width
+  IO.console&.winsize&.last || 120
+rescue StandardError
+  120
+end
+```
+
+You'll need `require 'io/console'` — add it at the top of the file (after `# frozen_string_literal: true`):
+```ruby
+require 'io/console'
+```
+
+### Step 2 — replace hardcoded separator lengths
+
+Currently the file has multiple `puts '-' * N` lines with hardcoded widths (133, 122, 189, 200, etc.).
+
+Replace each with `puts '-' * [terminal_width, N].min` where N is the original value. This prevents the separator from overflowing narrow terminals while still using the full width on wide ones.
+
+grep for `'-'` in project_listing.rb to find all occurrences.
+
+### Step 3 — add path truncation helper
+
+```ruby
+def self.truncate_path(path, max_width = 35)
+  return path if path.nil? || path.length <= max_width
+  "...#{path[-(max_width - 3)..]}"
+end
+```
+
+Replace `shorten_path(data[:path])` calls with `truncate_path(shorten_path(data[:path]), 35)` where the format string uses `%-35s`.
+
+### Done when B010 is complete
+- `RUBYOPT="-W0" bundle exec rspec spec/appydave/tools/dam/project_listing_spec.rb` → all pass
+- `RUBYOPT="-W0" bundle exec rspec` → 860+ examples, 0 failures
+- `bundle exec rubocop --format clang` → 0 offenses
+- Commit: `kfix "terminal-width-aware separator lines and path truncation in project_listing"`
+
+---
+
+## B012 — brand-resolution-integration-tests
+
+**File:** `spec/appydave/tools/dam/brand_resolution_integration_spec.rb` (new file)
+
+### What to build
+
+Integration tests that exercise the BrandResolver → Config → ProjectResolver chain end-to-end using the shared filesystem context.
+
+```ruby
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'Brand resolution integration' 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(appydave_path, 'b66-another-project'))
+    FileUtils.mkdir_p(File.join(voz_path, 'boy-baker'))
+  end
+
+  describe 'BrandResolver → Config.brand_path' do
+    it 'resolves appydave shortcut to correct path' do
+      path = Appydave::Tools::Dam::Config.brand_path('appydave')
+      expect(path).to eq(appydave_path)
+    end
+
+    it 'resolves voz shortcut to correct path' do
+      path = Appydave::Tools::Dam::Config.brand_path('voz')
+      expect(path).to eq(voz_path)
+    end
+
+    it 'raises BrandNotFoundError for unknown brand' do
+      expect { Appydave::Tools::Dam::Config.brand_path('nonexistent') }
+        .to raise_error(Appydave::Tools::Dam::BrandNotFoundError)
+    end
+  end
+
+  describe 'BrandResolver.expand' do
+    it 'expands appydave to v-appydave' do
+      expect(Appydave::Tools::Dam::BrandResolver.expand('appydave')).to eq('v-appydave')
+    end
+
+    it 'expands voz to v-voz' do
+      expect(Appydave::Tools::Dam::BrandResolver.expand('voz')).to eq('v-voz')
+    end
+  end
+
+  describe 'ProjectResolver.resolve' do
+    it 'resolves short name b65 to full project name' do
+      result = Appydave::Tools::Dam::ProjectResolver.resolve('appydave', 'b65')
+      expect(result).to eq('b65-test-project')
+    end
+
+    it 'resolves exact project name' do
+      result = Appydave::Tools::Dam::ProjectResolver.resolve('voz', 'boy-baker')
+      expect(result).to eq('boy-baker')
+    end
+
+    it 'raises ProjectNotFoundError for missing project' do
+      expect { Appydave::Tools::Dam::ProjectResolver.resolve('appydave', 'b99') }
+        .to raise_error(Appydave::Tools::Dam::ProjectNotFoundError)
+    end
+  end
+
+  describe 'ProjectResolver.detect_from_pwd' do
+    it 'detects brand and project from a project directory' do
+      Dir.chdir(File.join(appydave_path, 'b65-test-project')) do
+        brand, project = Appydave::Tools::Dam::ProjectResolver.detect_from_pwd
+        expect(brand).to eq('appydave')
+        expect(project).to eq('b65-test-project')
+      end
+    end
+
+    it 'returns nil when run outside any known brand directory' do
+      Dir.chdir('/tmp') do
+        brand, project = Appydave::Tools::Dam::ProjectResolver.detect_from_pwd
+        expect(brand).to be_nil
+        expect(project).to be_nil
+      end
+    end
+  end
+end
+```
+
+**Read `project_resolver.rb` and `brand_resolver.rb` before writing** to confirm method signatures.
+
+**Note:** The shared context mocks `SettingsConfig#video_projects_root` to return `projects_root`, so `Config.brand_path` calls will resolve to the temp filesystem. `instance_double` is NOT needed here — use the real classes against the mocked filesystem.
+
+### Done when B012 is complete
+- `bundle exec rspec spec/appydave/tools/dam/brand_resolution_integration_spec.rb` → all pass
+- `RUBYOPT="-W0" bundle exec rspec` → 866+ examples, 0 failures
+- `bundle exec rubocop --format clang` → 0 offenses
+- Commit: `kfix "add brand resolution integration spec covering BrandResolver, Config, ProjectResolver chain"`
+
+---
+
+## Success Criteria (Every Work Unit)
+
+- [ ] `RUBYOPT="-W0" bundle exec rspec` → 860+ examples, 0 failures
+- [ ] `bundle exec rubocop --format clang` → 0 offenses
+- [ ] Coverage ≥ 86.44%
+- [ ] Working tree clean before calling kfix/kfeat (git status check)
+
+---
+
+## Reference Patterns
+
+### Shared Context for DAM Specs
+
+```ruby
+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 → projects_root
+```
+
+### instance_double — Always Full Constant
+
+```ruby
+instance_double(Appydave::Tools::Configuration::Models::BrandsConfig)  # ✅
+instance_double('BrandsConfig')                                          # ❌ fails CI
+```
+
+### Typed Exceptions
+
+```ruby
+raise Appydave::Tools::Dam::BrandNotFoundError.new(brand, available, suggestions)
+raise Appydave::Tools::Dam::ProjectNotFoundError, 'message'
+raise Appydave::Tools::Dam::UsageError, 'message'
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- ❌ `exit 1` in library code — use typed exceptions
+- ❌ `instance_double('StringForm')` — fails CI on Ubuntu
+- ❌ Multiple `before` blocks in same context — merge them (RSpec/ScatteredSetup)
+- ❌ `$?` for subprocess status — use `$CHILD_STATUS`
+- ❌ `format_bytes` — use `FileHelper.format_size`
+- ❌ Inline brand transforms — use BrandResolver
+
+---
+
+## Learnings
+
+### From env-dead-code-cleanup (2026-03-20)
+
+- **kfix runs `git add .` internally.** Clean the working tree before calling kfix. Check `git status` first.
+- **`instance_double` string form fails CI on Ubuntu.** Always use full constant.
+- **`not_to raise_error` is a weak assertion.** Prefer field-value or method-spy assertions.
+
+### From library-boundary-cleanup (2026-03-20)
+
+- **`exit 1` in library code → use typed exceptions.** VatCLI rescue blocks catch StandardError.
+- **Config.brands needs separate mock** from shared filesystem context.
+- **S3ScanCommand#scan_all rescues per-brand** — per-brand failures are isolated.

data/docs/planning/batch-a-features/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,37 @@
+# IMPLEMENTATION_PLAN.md — batch-a-features
+
+**Goal**: Four independent improvements batched into one parallel wave: token counting for gpt_context, progress indicators for dam S3 commands, terminal-width-aware column separators, and brand resolution integration tests.
+**Started**: 2026-03-20
+**Target**: All 4 complete, 860+ examples passing, rubocop 0 offenses
+
+## Summary
+- Total: 4 | Complete: 0 | In Progress: 4 | Pending: 0 | Failed: 0
+
+## Pending
+
+## In Progress
+- [~] B001 — gpt-context-token-counting — Add --tokens flag to gpt_context; print estimated token count + threshold warnings
+- [~] B009 — dam-progress-indicators — Add before/after progress messages to s3_up, s3_down, s3_status, archive, sync_ssd in bin/dam
+- [~] B010 — dam-column-widths — Terminal-width-aware separator lines + path truncation in project_listing.rb
+- [~] B012 — brand-resolution-integration-tests — Integration spec covering brand→project resolution chain end-to-end
+
+## Complete
+
+## Failed / Needs Retry
+
+## Notes & Decisions
+
+### Wave Plan
+All 4 work units touch different files — run in parallel, one wave.
+
+| WU | Files |
+|----|-------|
+| B001 | `lib/gpt_context/options.rb`, `bin/gpt_context.rb` |
+| B009 | `bin/dam` |
+| B010 | `lib/dam/project_listing.rb` |
+| B012 | `spec/appydave/tools/dam/brand_resolution_integration_spec.rb` (new) |
+
+### kfix hygiene
+kfix runs `git add .` internally. Ensure working tree contains ONLY intended files before calling kfix.
+The other agents' in-progress changes will NOT appear in your working tree (each agent works independently).
+Safe to call kfix once your specific files are the only changes present.

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

@@ -17,22 +17,32 @@
 
 ## ⚠️ Pre-Commit Check (Mandatory Every Commit)
 
+`kfix` and `kfeat` run `git add .` internally — they stage EVERYTHING in the working tree unconditionally. You cannot selectively stage files.
+
+**The only safe approach: ensure the working tree contains ONLY your intended changes before calling kfix.**
+
 ```bash
-git status
+git status          # What files are modified/untracked?
+git diff            # What are the actual changes?
 ```
 
-Confirm ONLY the files you intentionally changed are staged. **Stage by file name — never `git add .` or `git add -A`.**
+If unintended files appear (e.g. planning docs, other specs):
+- `git stash -- path/to/file` to temporarily stash a specific file
+- OR `git checkout -- path/to/file` to discard an unintended change
+- OR `git clean -n` to preview, then `git clean -f path/to/file` for untracked files
 
+Once the working tree contains ONLY the files you intended to change, call:
 ```bash
-# Correct:
-git add bin/dam
-kfix "..."
-
-# Wrong — stages everything including planning files:
-git add .
+kfix "your message here"
 ```
 
-**Why:** Three prior campaigns have had accidental staging from `git add .`. It is the single most common failure mode in this repo.
+kfix/kfeat then:
+1. `git add .` — stages everything (working tree must be clean of unintended files)
+2. `git commit -m "fix: ..."` — commits
+3. `git pull` + `git push` — syncs and pushes
+4. Waits for CI (`gh run watch`) — blocks until green or red
+5. On success: `git pull` again to pick up semantic-release version bump + CHANGELOG
+6. Prints the new version tag
 
 ---
 
@@ -104,7 +114,7 @@ After removing, also check if `options[:brand_path]` was the ONLY use of `option
 - `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)
+- `git status` clean (working tree contains ONLY bin/dam changes before calling kfix)
 
 **Commit:** `kfix "remove ENV BRAND_PATH dead code from bin/dam (10 assignments, never read in lib)"`
 
@@ -153,7 +163,7 @@ FileUtils.mkdir_p(File.join(appydave_path, 'b65-test-project', 's3-staging'))
 - `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)
+- `git status` clean (working tree contains ONLY the spec file changes before calling kfix)
 
 **Commit:** `kfix "strengthen s3_scan_command_spec field assertions; remove LocalSyncStatus stub"`
 
@@ -164,7 +174,7 @@ FileUtils.mkdir_p(File.join(appydave_path, 'b65-test-project', 's3-staging'))
 - [ ] `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 .`)
+- [ ] `git status` clean (working tree contains ONLY intended changes before calling kfix)
 
 ---
 
@@ -201,7 +211,7 @@ 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
+- ❌ Calling `kfix`/`kfeat` with unintended files in the working tree — clean the tree first, then call kfix
 - ❌ `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
@@ -216,7 +226,7 @@ raise Appydave::Tools::Dam::UsageError, 'Usage: dam s3-up <brand> <project>'
 ### 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.
+- **Dirty working tree + kfix = accidental staging.** `kfix` runs `git add .` internally — it stages everything. Ensure the working tree contains ONLY intended changes before calling kfix.
 - **`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.
 

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

@@ -5,13 +5,13 @@
 **Target**: Both items complete; 861+ examples passing; rubocop 0 offenses; no regressions
 
 ## Summary
-- Total: 2 | Complete: 0 | In Progress: 2 | Pending: 0 | Failed: 0
+- Total: 2 | Complete: 2 | In Progress: 0 | 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
+- [x] B038 — remove-env-dead-code — All 10 ENV['BRAND_PATH'] assignments removed from bin/dam; 0 cascade removals (options still used for other keys). CI fix needed: git add . staged s3_scan_command_spec.rb with pre-existing RSpec/RepeatedExample offense — fixed via second commit. 860 examples, 0 failures. Commits: 5c11027, 5711e4e.
+- [x] B039 — strengthen-s3-scan-spec — Field-value assertions on both not_to be_empty checks; LocalSyncStatus stub removed (runs for real against fixture filesystem, returns :no_files). 861 examples, 0 failures. v0.76.12. Commit: 7f1fc5a.
 
 ## Complete
 

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

@@ -0,0 +1,88 @@
+# Assessment: env-dead-code-cleanup
+
+**Campaign**: env-dead-code-cleanup
+**Date**: 2026-03-20 → 2026-03-20
+**Results**: 2 complete, 0 failed
+**Final version**: v0.76.13 (from v0.76.11 baseline)
+**Quality audits**: code-quality-audit ✅ | test-quality-audit ✅
+
+---
+
+## Results Summary
+
+| Work Unit | Description | Result | Version |
+|-----------|-------------|--------|---------|
+| B038 | remove-env-dead-code | ✅ Complete | v0.76.12/13 |
+| B039 | strengthen-s3-scan-spec | ✅ Complete | v0.76.12 |
+
+**Test baseline:** 861 → 860 examples (net -1: one redundant smoke test removed), 0 failures, 86.44% line coverage
+
+---
+
+## What Worked Well
+
+1. **Both work units ran in parallel with zero conflicts.** `bin/dam` and `spec/...` are non-overlapping. Wave 1 parallel pattern continues to be reliable for this type of work.
+
+2. **ENV removal was surgically clean.** All 10 assignments were isolated lines with no downstream reads — each method is 1 line shorter and more readable. Code audit confirmed 0 orphaned variables.
+
+3. **Test grade lifted from B to B+.** Field-value assertions now catch wrong values, not just non-empty. LocalSyncStatus runs for real (via fixture filesystem) and is verified with a method spy. Stronger than before without over-specifying.
+
+4. **Code audit: zero concerns.** 0 rubocop offenses, 0 remaining dead code, library boundaries respected everywhere.
+
+---
+
+## What Didn't Work
+
+1. **B038 agent used `git add .` again** — the fourth campaign in a row with this issue. It staged `s3_scan_command_spec.rb` which had a pre-existing `RSpec/RepeatedExample` offense on CI. Required a second fix commit. The AGENTS.md warning is prominent but agents keep ignoring it.
+
+   **Root cause:** The `kfix` alias may itself be running `git add .` internally, or agents are running `git add .` before `kfix`. Need to investigate whether `kfix` pre-stages, and if so, update AGENTS.md to reflect that.
+
+---
+
+## Key Learnings — Application
+
+1. **`ENV['BRAND_PATH']` is fully gone.** `grep -rn "BRAND_PATH" bin/ lib/ spec/` → 0 results. Any future S3 operations get `brand_path` through proper parameter passing.
+
+2. **`not_to raise_error` is a weak assertion.** It only verifies no exception — it says nothing about correctness. Replace with field-value or method-spy assertions whenever possible.
+
+3. **LocalSyncStatus integration test pattern:** Use `allow(Config).to receive(:project_path).and_return(appydave_path)` + `FileUtils.mkdir_p(staging_dir)` to let LocalSyncStatus run for real without deep mocking.
+
+---
+
+## Key Learnings — Ralph Loop
+
+1. **`git add .` persists across agents despite AGENTS.md warnings.** The warning is not working. Options for next campaign:
+   - Investigate whether `kfix` itself stages all files (check its shell implementation)
+   - Add explicit `git add <specific-file>` to commit instructions in AGENTS.md rather than relying on agents to remember not to use `git add .`
+
+2. **Small 2-WU parallel campaigns are very efficient.** Planning took ~5 minutes (brief already written), build ran in one wave, audits confirmed clean. This is the right pattern for closing audit findings.
+
+---
+
+## Code Quality Audit Findings
+
+**Grade: APPROVED / Production-ready**
+- 0 BRAND_PATH references anywhere in codebase
+- All removal sites clean — no orphaned variables
+- 0 rubocop offenses in bin/dam
+- 860/860 tests pass, 86.44% coverage
+
+---
+
+## Test Quality Audit Findings
+
+**Grade: B+ (improvement from B)**
+- Field-value assertions are not tautological — catch mutations to file_count, total_bytes, last_modified
+- LocalSyncStatus spy verifies correct arguments passed (not just that it doesn't raise)
+- Removed test was genuinely redundant — no coverage loss
+- Appropriate layer separation: S3ScanCommand spec tests orchestration; LocalSyncStatus spec tests computation
+
+---
+
+## Suggestions for Next Campaign
+
+1. **Investigate `kfix` staging behaviour** — check whether the alias runs `git add .` or `git add -A` before committing. If so, update AGENTS.md to use `git add <file> && kfix` pattern explicitly.
+
+2. **Next major work:** B020 (split S3Operations, 1,030 lines) — now the cleanest next step. Library boundaries are solid, dead code is gone, test suite is at B+.
+
+3. **B007 (parallelism)** follows B020 — do not attempt before S3Operations is split.

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

@@ -19,13 +19,32 @@
 
 ## ⚠️ Pre-Commit Check (Mandatory Every Commit)
 
-Before running `kfix`, always run:
+`kfix` and `kfeat` run `git add .` internally — they stage EVERYTHING in the working tree unconditionally. You cannot selectively stage files.
+
+**The only safe approach: ensure the working tree contains ONLY your intended changes before calling kfix.**
+
+```bash
+git status          # What files are modified/untracked?
+git diff            # What are the actual changes?
+```
+
+If unintended files appear (e.g. planning docs, other specs):
+- `git stash -- path/to/file` to temporarily stash a specific file
+- OR `git checkout -- path/to/file` to discard an unintended change
+- OR `git clean -n` to preview, then `git clean -f path/to/file` for untracked files
+
+Once the working tree contains ONLY the files you intended to change, call:
 ```bash
-git status
+kfix "your message here"
 ```
-Confirm ONLY the files you intentionally changed are staged. If unexpected files appear, run `git diff` to investigate before proceeding. Never commit files you didn't intentionally change.
 
-**Why:** Prior campaign accidentally staged a pre-existing uncommitted change when running `kfix`. Required a follow-up fix commit.
+kfix/kfeat then:
+1. `git add .` — stages everything (working tree must be clean of unintended files)
+2. `git commit -m "fix: ..."` — commits
+3. `git pull` + `git push` — syncs and pushes
+4. Waits for CI (`gh run watch`) — blocks until green or red
+5. On success: `git pull` again to pick up semantic-release version bump + CHANGELOG
+6. Prints the new version tag
 
 ---
 
@@ -648,7 +667,7 @@ end
 ### 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.
+- **Dirty working tree + kfix = accidental staging.** `kfix` runs `git add .` internally — it stages everything. Ensure the working tree contains ONLY intended changes before calling kfix. Three prior campaigns have been burned by this.
 - **`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)

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.76.13'
+    VERSION = '0.76.14'
   end
 end

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.76.13",
+  "version": "0.76.14",
   "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.76.13
+  version: 0.76.14
 platform: ruby
 authors:
 - David Cruwys
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-19 00:00:00.000000000 Z
+date: 2026-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -297,11 +297,14 @@ files:
 - docs/guides/tools/youtube-manager.md
 - docs/planning/AGENTS.md
 - docs/planning/BACKLOG.md
+- docs/planning/batch-a-features/AGENTS.md
+- docs/planning/batch-a-features/IMPLEMENTATION_PLAN.md
 - 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/env-dead-code-cleanup/assessment.md
 - docs/planning/extract-vat-cli/AGENTS.md
 - docs/planning/extract-vat-cli/IMPLEMENTATION_PLAN.md
 - docs/planning/extract-vat-cli/assessment.md