Merge pull request #177 from Sagargupta16/feat/tds-schedule

feat(tax): TDS schedule + clean-code & SonarCloud refactor passes

Author: Sagargupta16

.claude/skills/boy-scout/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: boy-scout
+description: Use when fixing, editing, changing, debugging, or working with any Python code. Applies the Boy Scout Rule—always leave code cleaner than you found it. Orchestrates other clean code skills as needed.
+when_to_use: |
+  Also trigger on: "while you're at it", "any quick wins", "improve this a bit", "anything else obviously wrong", or when editing existing Python and an adjacent small cleanup is possible alongside the asked-for change.
+---
+
+# The Boy Scout Rule
+
+> "Always leave the campground cleaner than you found it."
+> — Robert Baden-Powell
+
+> "Always check a module in cleaner than when you checked it out."
+> — Robert C. Martin, *Clean Code*
+
+## The Philosophy
+
+You don't have to make every module perfect. You simply have to make it **a little bit better** than when you found it.
+
+If we all followed this simple rule:
+- Our systems would gradually get better as they evolved
+- Teams would care for the system as a whole
+- The relentless deterioration of software would end
+
+## When Working on Code
+
+Every time you touch code, look for **at least one small improvement**:
+
+### Quick Wins (Do These Immediately)
+- Rename a poorly named variable → triggers `clean-names`
+- Delete a redundant comment → triggers `clean-comments`
+- Remove dead code or unused imports
+- Replace a magic number with a named constant
+- Extract a deeply nested block into a well-named function
+
+### Deeper Improvements (When Time Allows)
+- Split a function that does multiple things → triggers `clean-functions`
+- Remove duplication (DRY) → triggers `clean-general`
+- Add missing boundary checks
+- Improve test coverage → triggers `clean-tests`
+
+## The Rule in Practice
+
+```python
+# You're asked to fix a bug in this function:
+def proc(d, x, flag=False):
+    # process data
+    for i in d:
+        if i > 0:
+            if flag:
+                x.append(i * 1.0825)  # tax
+            else:
+                x.append(i)
+    return x
+
+# Don't just fix the bug and leave.
+# Leave it cleaner:
+TAX_RATE = 0.0825
+
+def process_positive_values(
+    values: list[float],
+    apply_tax: bool = False
+) -> list[float]:
+    """Filter positive values, optionally applying tax."""
+    rate = 1 + TAX_RATE if apply_tax else 1
+    return [v * rate for v in values if v > 0]
+```
+
+**What changed:**
+- ✅ Descriptive function name (N1)
+- ✅ Clear parameter names (N1)
+- ✅ Type hints (P3)
+- ✅ Named constant for magic number (G25)
+- ✅ No output argument mutation (F2)
+- ✅ Useful docstring (C4)
+
+## Skill Orchestration
+
+This skill coordinates with specialized skills based on what you're doing:
+
+| Task | Trigger Skill |
+|------|---------------|
+| Writing/reviewing any Python | `python-clean-code` (master) |
+| Naming variables, functions, classes | `clean-names` |
+| Writing or editing comments | `clean-comments` |
+| Creating or refactoring functions | `clean-functions` |
+| Reviewing code quality | `clean-general` |
+| Writing or reviewing tests | `clean-tests` |
+
+## The Mindset
+
+**Don't:**
+- Leave code worse than you found it
+- Say "that's not my code"
+- Wait for a dedicated refactoring sprint
+- Make massive changes unrelated to your task
+
+**Do:**
+- Make one small improvement with every commit
+- Fix what you see, even if you didn't break it
+- Keep changes proportional to your task
+- Leave a trail of quality improvements
+
+## AI Behavior
+
+When working on code:
+1. Complete the requested task first
+2. Identify at least one small cleanup opportunity
+3. Apply the appropriate specialized skill
+4. Note the improvement made (e.g., "Also cleaned up: renamed `x` to `results` for clarity")
+
+When reviewing code:
+1. Load `python-clean-code` for comprehensive rule checking
+2. Flag violations by rule number
+3. Suggest incremental improvements, not complete rewrites
+
+## The Boy Scout Promise
+
+Every piece of code you touch gets a little better. Not perfect—just better.
+
+Over time, better compounds into excellent.

.claude/skills/clean-comments/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: clean-comments
+description: Use when writing, fixing, editing, or reviewing Python comments and docstrings. Enforces Clean Code principles—no metadata, no redundancy, no commented-out code.
+when_to_use: |
+  Also trigger on: commented-out code blocks, TODO/FIXME banners, author/ticket/date metadata in comments, docstrings that no longer match the code, redundant comments that restate the code (e.g. `i += 1  # increment i`), or asks like "is this comment useful", "why is this block commented".
+---
+
+# Clean Comments
+
+## C1: No Inappropriate Information
+
+Comments shouldn't hold metadata. Use Git for author names, change history,
+ticket numbers, and dates. Comments are for technical notes about code only.
+
+## C2: Delete Obsolete Comments
+
+If a comment describes code that no longer exists or works differently,
+delete it immediately. Stale comments become "floating islands of
+irrelevance and misdirection."
+
+## C3: No Redundant Comments
+
+```python
+# Bad - the code already says this
+i += 1  # increment i
+user.save()  # save the user
+
+# Good - explains WHY, not WHAT
+i += 1  # compensate for zero-indexing in display
+```
+
+## C4: Write Comments Well
+
+If a comment is worth writing, write it well:
+- Choose words carefully
+- Use correct grammar
+- Don't ramble or state the obvious
+- Be brief
+
+## C5: Never Commit Commented-Out Code
+
+```python
+# DELETE THIS - it's an abomination
+# def old_calculate_tax(income):
+#     return income * 0.15
+```
+
+Who knows how old it is? Who knows if it's meaningful? Delete it.
+Git remembers everything.
+
+## The Goal
+
+The best comment is the code itself. If you need a comment to explain
+what code does, refactor first, comment last.

.claude/skills/clean-functions/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: clean-functions
+description: Use when writing, fixing, editing, or refactoring Python functions. Enforces Clean Code principles—maximum 3 arguments, single responsibility, no flag parameters.
+when_to_use: |
+  Also trigger on: functions with 4+ parameters, boolean flag parameters like `enabled=True`, functions that mutate their arguments in place, one-off `util`/`helper` functions that are never called, or asks like "too many arguments", "split this function", "is this still used".
+---
+
+# Clean Functions
+
+## F1: Too Many Arguments (Maximum 3)
+
+```python
+# Bad - too many parameters
+def create_user(name, email, age, country, timezone, language, newsletter):
+    ...
+
+# Good - use a dataclass or dict
+@dataclass
+class UserData:
+    name: str
+    email: str
+    age: int
+    country: str
+    timezone: str
+    language: str
+    newsletter: bool
+
+def create_user(data: UserData):
+    ...
+```
+
+More than 3 arguments means your function is doing too much or needs
+a data structure.
+
+## F2: No Output Arguments
+
+Don't modify arguments as side effects. Return values instead.
+
+```python
+# Bad - modifies argument
+def append_footer(report: Report) -> None:
+    report.append("\n---\nGenerated by System")
+
+# Good - returns new value
+def with_footer(report: Report) -> Report:
+    return report + "\n---\nGenerated by System"
+```
+
+## F3: No Flag Arguments
+
+Boolean flags mean your function does at least two things.
+
+```python
+# Bad - function does two different things
+def render(is_test: bool):
+    if is_test:
+        render_test_page()
+    else:
+        render_production_page()
+
+# Good - split into two functions
+def render_test_page(): ...
+def render_production_page(): ...
+```
+
+## F4: Delete Dead Functions
+
+If it's not called, delete it. No "just in case" code. Git preserves history.

.claude/skills/clean-general/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: clean-general
+description: Use when writing, fixing, editing, or reviewing Python code quality. Enforces Clean Code's core principles—DRY, single responsibility, clear intent, no magic numbers, proper abstractions.
+when_to_use: |
+  Also trigger on: duplicated logic across files or branches (G5), magic numbers or hardcoded values (G25), long if/elif chains that should be polymorphism (G23), chained property access like `a.b.c.d` (G36), functions juggling multiple responsibilities (G30), clever one-liners whose intent is not obvious (G16).
+---
+
+# General Clean Code Principles
+
+## Critical Rules
+
+**G5: DRY (Don't Repeat Yourself)**
+
+Every piece of knowledge has one authoritative representation.
+
+```python
+# Bad - duplication
+tax_rate = 0.0825
+ca_total = subtotal * 1.0825
+ny_total = subtotal * 1.07
+
+# Good - single source of truth
+TAX_RATES = {"CA": 0.0825, "NY": 0.07}
+def calculate_total(subtotal: float, state: str) -> float:
+    return subtotal * (1 + TAX_RATES[state])
+```
+
+**G16: No Obscured Intent**
+
+Don't be clever. Be clear.
+
+```python
+# Bad - what does this do?
+return (x & 0x0F) << 4 | (y & 0x0F)
+
+# Good - obvious intent
+return pack_coordinates(x, y)
+```
+
+**G23: Prefer Polymorphism to If/Else**
+
+```python
+# Bad - will grow forever
+def calculate_pay(employee):
+    if employee.type == "SALARIED":
+        return employee.salary
+    elif employee.type == "HOURLY":
+        return employee.hours * employee.rate
+    elif employee.type == "COMMISSIONED":
+        return employee.base + employee.commission
+
+# Good - open/closed principle
+class SalariedEmployee:
+    def calculate_pay(self): return self.salary
+
+class HourlyEmployee:
+    def calculate_pay(self): return self.hours * self.rate
+
+class CommissionedEmployee:
+    def calculate_pay(self): return self.base + self.commission
+```
+
+**G25: Replace Magic Numbers with Named Constants**
+
+```python
+# Bad
+if elapsed_time > 86400:
+    ...
+
+# Good
+SECONDS_PER_DAY = 86400
+if elapsed_time > SECONDS_PER_DAY:
+    ...
+```
+
+**G30: Functions Should Do One Thing**
+
+If you can extract another function, your function does more than one thing.
+
+**G36: Law of Demeter (Avoid Train Wrecks)**
+
+```python
+# Bad - reaching through multiple objects
+output_dir = context.options.scratch_dir.absolute_path
+
+# Good - one dot
+output_dir = context.get_scratch_dir()
+```
+
+## Enforcement Checklist
+
+When reviewing AI-generated code, verify:
+- [ ] No duplication (G5)
+- [ ] Clear intent, no magic numbers (G16, G25)
+- [ ] Polymorphism over conditionals (G23)
+- [ ] Functions do one thing (G30)
+- [ ] No Law of Demeter violations (G36)
+- [ ] Boundary conditions handled (G3)
+- [ ] Dead code removed (G9)