Invoice Chaser: calculate late fees and choose a reminder stage

The Stack

Steps

1. 1

   Obtain the exact MIT sample and run its offline checks

   Run in a fresh directory. The script uses the reviewed archive bundled with FlowStacks, checks its SHA-256 and exact file inventory before extraction, retains the full MIT notice, and executes the published example and 18 upstream tests. The October 30 ZIP has a different checksum from the October 24 submission because its README and changelog were updated; the calculator remains unchanged. Nothing from the paid pack is required. This step does not install a skill in your account or send an invoice anywhere.

   #!/bin/sh
   # Execute the reviewed MIT sample unchanged. No Claude account or real invoice is used.
   set -eu
   
   OUTPUT_DIR=kitwise-invoice-chaser-flowstacks
   ARCHIVE=kitwise-invoice-chaser-sample-v1.0.0-3c9afa69.zip
   if [ -e "$OUTPUT_DIR" ]; then
     echo "Refusing to overwrite $OUTPUT_DIR; use a fresh directory." >&2
     exit 1
   fi
   mkdir "$OUTPUT_DIR"
   cd "$OUTPUT_DIR"
   
   # CI uses the checked-in artifact; readers can download the same public copy.
   if [ -n "${FLOWSTACKS_KITWISE_ARCHIVE:-}" ]; then
     cp "$FLOWSTACKS_KITWISE_ARCHIVE" sample.zip
   elif [ -n "${GITHUB_WORKSPACE:-}" ] && [ -f "$GITHUB_WORKSPACE/public/downloads/$ARCHIVE" ]; then
     cp "$GITHUB_WORKSPACE/public/downloads/$ARCHIVE" sample.zip
   else
     curl --disable --proto '=https' --tlsv1.2 --max-time 30 --max-filesize 131072 -fsS \
       "https://flowstacks.xyz/downloads/$ARCHIVE" -o sample.zip
   fi
   
   python3 -I <<'PY'
   import hashlib
   import json
   import pathlib
   import subprocess
   import sys
   import zipfile
   from decimal import Decimal
   
   archive = pathlib.Path('sample.zip').read_bytes()
   assert hashlib.sha256(archive).hexdigest() == '3c9afa69bfb82f7a0164897534be1031e880f0ad3df3f9d7af6cce99fba5302d', 'sample checksum changed'
   prefix = 'invoice-chaser-sample-v1.0.0/'
   expected = {
       'CHANGELOG.md', 'LICENSE', 'README.md', 'expected-script-output.json', 'run-script.sh',
       'invoice-chaser/SKILL.md', 'invoice-chaser/scripts/late_fee.py',
       'invoice-chaser/references/fee-method.md', 'invoice-chaser/references/stages.md',
       'tests/test_late_fee.py',
   }
   with zipfile.ZipFile('sample.zip') as bundle:
       entries = bundle.infolist()
       assert len(entries) == len(expected)
       assert {item.filename for item in entries} == {prefix + name for name in expected}
       assert sum(item.file_size for item in entries) < 65536
       for item in entries:
           path = pathlib.PurePosixPath(item.filename)
           assert not path.is_absolute() and '..' not in path.parts and '\\' not in item.filename
           assert (item.external_attr >> 16) & 0o170000 != 0o120000, 'symlink not allowed'
       bundle.extractall('.')
   
   root = pathlib.Path(prefix).resolve()
   license_text = (root / 'LICENSE').read_text()
   assert 'MIT License' in license_text and 'Copyright (c) 2026 Kitwise Studio' in license_text
   for name in ['scripts/late_fee.py', 'references/stages.md', 'references/fee-method.md']:
       assert (root / 'invoice-chaser' / name).is_file()
   # Keep the copyright/permission notice with a separately uploaded skill folder too.
   (root / 'invoice-chaser' / 'LICENSE').write_text(license_text)
   print('Kitwise source pinned OK: sample 1.0.0, SHA-256 3c9afa69, MIT notice retained')
   
   runner = subprocess.run(['bash', 'run-script.sh'], cwd=root, capture_output=True, text=True, timeout=20)
   assert runner.returncode == 0 and 'PASS: output matches' in runner.stdout, runner.stdout + runner.stderr
   tests = subprocess.run([sys.executable, '-I', 'tests/test_late_fee.py'], cwd=root, capture_output=True, text=True, timeout=30)
   assert tests.returncode == 0 and 'Ran 18 tests' in tests.stderr, tests.stdout + tests.stderr
   print('Kitwise upstream checks OK: exact example and 18 regression tests')
   
   script = root / 'invoice-chaser/scripts/late_fee.py'
   def calculate(**overrides):
       values = {'amount': '2400', 'due': '2026-09-15', 'today': '2026-10-16', 'monthly-rate': '0.015'}
       values.update({key.replace('_', '-'): str(value) for key, value in overrides.items()})
       args = [sys.executable, '-I', str(script)]
       for key, value in values.items():
           args.extend(['--' + key, value])
       done = subprocess.run(args, capture_output=True, text=True, timeout=5)
       result = json.loads(done.stdout, parse_float=Decimal,
                           parse_constant=lambda value: (_ for _ in ()).throw(ValueError(value)))
       return done.returncode, result
   
   code, normal = calculate()
   assert code == 0 and normal['days_overdue'] == 31 and normal['late_fee'] == Decimal('36.69')
   assert normal['total_due'] == Decimal('2436.69') and normal['stage'] == 3
   assert calculate(cap_pct='0.01')[1]['fee_per_extra_week'] == 0
   assert calculate(monthly_rate='0')[1]['late_fee'] == 0
   assert calculate(amount='91.25', today='2026-09-16')[1]['late_fee'] == Decimal('0.05')
   assert calculate(today='2026-09-25', reminders_sent=2)[1]['stage'] == 3
   assert calculate(today='2026-09-10', reminders_sent=4)[1]['stage'] == 0
   for override, field in [({'amount': 'nan'}, 'amount'), ({'amount': '0'}, 'amount'),
                           ({'grace': '-1'}, 'grace'), ({'monthly_rate': '-0.01'}, 'monthly_rate')]:
       code, result = calculate(**override)
       assert code == 2 and result['field'] == field and 'error' in result
   print('Kitwise independent checks OK: cents, half-up rounding, cap, no fee, reminder history and JSON errors')
   print('Scope: cent-denominated inputs; weekly growth is an estimate; fractional-cent behavior is not corrected')
   print('No Claude execution, email drafting or sending, paid pack, or legal entitlement was verified')
   PY
   
   printf 'Sample and MIT license are in %s/invoice-chaser-sample-v1.0.0/\n' "$OUTPUT_DIR"
   

2. 2

   Calculate using your actual terms and an explicit date

   From kitwise-invoice-chaser-flowstacks/invoice-chaser-sample-v1.0.0, run: python3 invoice-chaser/scripts/late_fee.py --amount 2400 --due 2026-09-15 --today 2026-10-16 --monthly-rate 0.015 --reminders-sent 2. Replace every value with your own agreed terms; rate 0 is appropriate if no fee was agreed. Use whole-cent principal and flat fees only. The fixed example gives stage_by_days 3 and stage 3; reminders-sent means the highest stage previously sent, not a count of emails. Weekly growth is an estimate from unrounded fees: this example's rounded balance rises by 8.29 over seven days even though the weekly estimate is 8.28. Do not use fractional-cent or extreme inputs, and stop on errors or unreconciled totals.

3. 3

   Optionally inspect the new skill in Claude

   Package the extracted invoice-chaser folder, including its copied LICENSE, as a ZIP and upload it using Claude's custom-skill controls with code execution enabled. The free sample explains calculation and stage selection only. Ask it to run the script with synthetic inputs first and compare every number yourself. FlowStacks has not executed this new skill in Claude. It contains no email templates; any separate drafting step and all client communications require your own review and are outside the badge.