nightytidy 0.1.0

package/src/prompts/steps/09-dependency-health.md

@@ -0,0 +1,217 @@
+# Dependency Health & Upgrade Pass
+
+## Prompt
+
+```
+You are running an overnight dependency health audit and upgrade pass. You have several hours. Your job is to assess the health, risk, and maintainability of every external dependency in the project — then upgrade what's safe and document the rest.
+
+Work on a branch called `dependency-health-[date]`.
+
+## Your Mission
+
+### Phase 1: Dependency Inventory
+
+**Step 1: Catalog every dependency**
+Read all dependency manifests (package.json, requirements.txt, Cargo.toml, go.mod, Gemfile, pom.xml, etc.) and create a complete inventory:
+
+For each dependency:
+- Name and current version
+- Latest available version
+- How far behind the project is (patch / minor / major versions behind)
+- What it's used for in this project (read the code, don't guess)
+- How widely it's imported (used in 1 file or 50?)
+- Whether it's a direct dependency or transitive
+- Whether it's a runtime dependency or dev-only
+
+**Step 2: Catalog lock file status**
+- Is there a lock file (package-lock.json, yarn.lock, poetry.lock, Cargo.lock, etc.)?
+- Is it committed to the repo?
+- Is it consistent with the manifest? (Run install and check for drift)
+- Are there duplicate packages at different versions in the dependency tree?
+
+### Phase 2: Health Assessment
+
+**Step 1: Identify abandoned or risky dependencies**
+For each dependency, assess its health:
+
+- **Last published**: When was the last release? Dependencies with no release in 2+ years are a risk.
+- **Maintenance signals**: Open issue count, unmerged PRs, maintainer activity (use web search to check npm/PyPI/crates.io pages and GitHub repos)
+- **Known vulnerabilities**: Run `npm audit` / `pip audit` / `cargo audit` / equivalent. For each CVE:
+- Severity (critical/high/medium/low)
+- Is the vulnerable code path actually used in this project?
+- Is there a patched version available?
+- Is the fix a simple version bump or a breaking change?
+- **Bus factor**: Is this maintained by one person? Is it a critical dependency maintained by an unfunded individual? (This is a real supply chain risk)
+
+**Step 2: License compliance scan**
+For every dependency (including transitive dependencies):
+- What license does it use?
+- Flag any that are:
+- **GPL/AGPL** in a proprietary or non-GPL project (potential copyleft risk)
+- **SSPL** or **BSL** (may restrict commercial use)
+- **No license specified** (legally risky — no license means no permission to use)
+- **Custom or unusual licenses** that need legal review
+- Generate a complete license inventory table
+- If the project has a declared license, flag any dependency license that's incompatible with it
+
+**Step 3: Dependency weight analysis**
+Identify dependencies that are disproportionately heavy:
+- Packages that pull in massive transitive dependency trees for minimal functionality
+- Packages where only a small fraction of the library is actually used (e.g., importing all of lodash for `_.get`)
+- Multiple packages that do similar things (two date libraries, two HTTP clients, two validation libraries)
+- Packages that could be replaced with native language features (e.g., `is-odd`, `left-pad` style micro-packages, or libraries superseded by modern language features)
+
+For each heavy/redundant dependency:
+- What is it and what's it used for?
+- How much of it is actually used?
+- What's the lighter alternative? (native feature, smaller package, or inline implementation)
+- Estimated effort to replace it
+
+### Phase 3: Safe Upgrades
+
+**Step 1: Upgrade patch versions**
+- Bump all dependencies to their latest patch version (X.Y.Z → X.Y.latest)
+- Run the full test suite after each batch of upgrades
+- These should be safe — patch versions are supposed to be backward compatible
+- If any tests fail, revert that specific upgrade and document the failure
+- Commit: `chore: bump patch versions for [scope]`
+
+**Step 2: Upgrade minor versions**
+- Bump dependencies to their latest minor version one at a time (X.Y → X.latest.latest)
+- Run tests after each upgrade
+- Minor versions may introduce new features but should be backward compatible
+- If tests fail, revert and document
+- Commit: `chore: bump [package] to [version]`
+
+**Step 3: Document major version upgrades**
+Major version upgrades are too risky for an overnight pass. For each dependency that's one or more major versions behind:
+- What breaking changes were introduced? (Read the changelog/migration guide)
+- What code in this project would need to change?
+- Estimated effort: trivial / moderate / significant
+- Priority: how important is this upgrade? (Security fix? Performance improvement? Just new features?)
+- Dependencies on other upgrades (does upgrading X require also upgrading Y?)
+
+**Step 4: Attempt low-risk major upgrades**
+If any major upgrades look trivial (changelog says "renamed one function" or "dropped Node 12 support"):
+- Attempt the upgrade
+- Run tests
+- If they pass, commit: `chore: upgrade [package] from [old] to [new]`
+- If they fail, revert and add to the documentation with notes on what broke
+
+### Phase 4: Dependency Reduction Opportunities
+
+**Step 1: Find removable dependencies**
+- Scan for dependencies that are imported in the manifest but never actually used in the source code
+- Scan for dependencies that are only used in commented-out or dead code
+- Check for dependencies that duplicate built-in functionality (e.g., a polyfill for something the minimum supported runtime already supports)
+
+**Step 2: Find replaceable dependencies**
+- Identify packages that can be replaced with a few lines of utility code (especially micro-packages)
+- Identify packages where only one function/feature is used and that function could be inlined
+- Identify packages with lighter, actively maintained alternatives
+
+**Step 3: Implement safe removals**
+- Remove clearly unused dependencies
+- Run tests
+- Commit: `chore: remove unused dependency [package]`
+
+DO NOT replace or inline dependencies in this pass unless it's trivially simple. Document replacement opportunities for the team.
+
+## Output Requirements
+
+Create the `audit-reports/` directory in the project root if it doesn't already exist. Save the report as `audit-reports/09_DEPENDENCY_HEALTH_REPORT_[run-number]_[date]_[time in user's local time].md` (e.g., `09_DEPENDENCY_HEALTH_REPORT_01_2026-02-16_2129.md`). Increment the run number based on any existing reports with the same name prefix in that folder.
+
+### Report Structure
+
+1. **Executive Summary**
+- Total dependencies: X (Y direct, Z transitive)
+- Dependencies with known vulnerabilities: X
+- Dependencies 1+ major versions behind: X
+- Potentially abandoned dependencies: X
+- License risks found: X
+- Upgrades applied: X
+- Dependencies removed: X
+
+2. **Vulnerability Report**
+- Table: | Package | CVE | Severity | Used in Project? | Fix Available? | Fix Applied? |
+- Vulnerabilities that couldn't be fixed and why
+
+3. **License Compliance**
+- Complete license inventory: table with | Package | License | Risk Level | Notes |
+- Flagged licenses that need legal review
+- Recommendation for ongoing license monitoring
+
+4. **Staleness Report**
+- Table: | Package | Current | Latest | Versions Behind | Last Published | Health |
+- Sorted by risk (most behind + least maintained first)
+
+5. **Upgrades Applied**
+- Table: | Package | From | To | Tests Pass? |
+- Any issues encountered during upgrades
+
+6. **Major Upgrades Needed (Not Applied)**
+- Table: | Package | Current | Target | Breaking Changes | Effort | Priority |
+- Suggested upgrade order (accounting for dependencies between upgrades)
+
+7. **Dependency Weight & Reduction**
+- Heavy dependencies: table with | Package | Size/Impact | Usage | Alternative | Effort |
+- Unused dependencies removed
+- Replacement opportunities for team review
+
+8. **Abandoned/At-Risk Dependencies**
+- Table: | Package | Last Release | Maintainer Activity | Risk | Recommendation |
+
+9. **Recommendations**
+- Priority-ordered action items
+- Suggested tooling for ongoing dependency health (Dependabot, Renovate, Snyk, etc.)
+- Suggested policy for dependency additions (criteria for adopting new dependencies)
+
+## Rules
+- Branch: `dependency-health-[date]`
+- Run full test suite after every upgrade attempt
+- If tests fail after an upgrade, revert IMMEDIATELY — don't debug the upgrade, just document it
+- DO NOT attempt major version upgrades unless the changelog clearly indicates the change is trivial for this project
+- DO NOT replace or rewrite dependencies overnight — only remove unused ones
+- For license assessment: flag risks, don't make legal determinations. The team needs to decide acceptable license policy.
+- Use web search to check dependency health (npm page, GitHub repo, last release date, open issues)
+- Be conservative. A working codebase with old dependencies is better than a broken codebase with new ones.
+- You have all night. Be thorough. Check every dependency.
+```
+
+## Chat Output Requirement
+
+In addition to writing the full report file, you MUST print a summary directly in the conversation when you finish. Do not make the user open the report to get the highlights. The chat summary should include:
+
+### 1. Status Line
+One sentence: what you did, how long it took, and whether all tests still pass.
+
+### 2. Key Findings
+The most important things discovered — bugs, risks, wins, or surprises. Each bullet should be specific and actionable, not vague. Lead with severity or impact.
+
+**Good:** "CRITICAL: No backup configuration found for the primary Postgres database — total data loss risk."
+**Bad:** "Found some issues with backups."
+
+### 3. Changes Made (if applicable)
+Bullet list of what was actually modified, added, or removed. Skip this section for read-only analysis runs.
+
+### 4. Recommendations
+
+If there are legitimately beneficial recommendations worth pursuing right now, present them in a table. Do **not** force recommendations — if the audit surfaced no actionable improvements, simply state that no recommendations are warranted at this time and move on.
+
+When recommendations exist, use this table format:
+
+| # | Recommendation | Impact | Risk if Ignored | Worth Doing? | Details |
+|---|---|---|---|---|---|
+| *Sequential number* | *Short description (≤10 words)* | *What improves if addressed* | *Low / Medium / High / Critical* | *Yes / Probably / Only if time allows* | *1–3 sentences explaining the reasoning, context, or implementation guidance* |
+
+Order rows by risk descending (Critical → High → Medium → Low). Be honest in the "Worth Doing?" column — not everything flagged is worth the engineering time. If a recommendation is marginal, say so.
+
+### 5. Report Location
+State the full path to the detailed report file for deeper review.
+
+---
+
+**Formatting rules for chat output:**
+- Use markdown headers, bold for severity labels, and bullet points for scannability.
+- Do not duplicate the full report contents — just the highlights and recommendations.
+- If you made zero findings in a phase, say so in one line rather than omitting it silently.

package/src/prompts/steps/10-codebase-cleanup.md

@@ -0,0 +1,189 @@
+# The Codebase Cleanup (Updated)
+
+## Prompt
+
+```
+You are running an overnight codebase cleanup. You have several hours — be thorough and methodical. Unlike a security audit, you will actually be making changes to the code. Every change must keep tests passing.
+
+## Your Mission
+
+Conduct a comprehensive codebase cleanup covering five areas. Work on a branch called `codebase-cleanup-[date]`. After EVERY meaningful change, run the test suite. If tests break, revert and document the issue instead of shipping the broken change.
+
+### Phase 1: Dead Code Elimination
+Systematically identify and remove:
+- **Unused exports**: Functions, classes, constants, and types that are exported but never imported anywhere
+- **Unused imports**: Imports that exist but aren't referenced in the file
+- **Unreachable code**: Code after return/throw statements, permanently false conditionals, disabled feature flags that will never be re-enabled
+- **Orphaned files**: Files that are never imported or referenced by any other file (be careful — check for dynamic imports, config references, and script entries)
+- **Unused dependencies**: Packages in package.json (or equivalent) that are never imported in the source code
+- **Commented-out code blocks**: Large blocks of commented-out code (not explanatory comments — actual dead code that's been commented out). If it's in version control, it doesn't need to be preserved as comments.
+
+**Process for each removal:**
+1. Identify the dead code
+2. Verify it's truly unused (search for dynamic references, string-based imports, reflection, etc.)
+3. Remove it
+4. Run tests
+5. If tests pass, commit with a clear message: `chore: remove unused [description]`
+6. If tests fail, revert and note it in the report as "appears unused but tests depend on it — investigate"
+
+### Phase 2: Code Duplication Reduction
+- Scan for duplicated or near-duplicated logic (functions that do roughly the same thing with minor variations)
+- Focus on:
+- Copy-pasted utility functions that exist in multiple files
+- Similar data transformation logic repeated across modules
+- Repeated validation patterns that could be a shared validator
+- Similar API call patterns that could be a shared client method
+- For each instance of significant duplication:
+- If the fix is low-risk (extracting a shared utility, creating a helper function): implement it, run tests, commit
+- If the fix is higher-risk (refactoring core patterns): document it in the report with a proposed approach, but don't implement
+
+### Phase 3: Consistency Enforcement
+Scan for and fix inconsistencies in:
+- **Naming conventions**: Mixed camelCase/snake_case in the same language, inconsistent file naming patterns, inconsistent component naming
+- **Import ordering**: Standardize to a consistent pattern (external deps → internal modules → relative imports → types)
+- **Error handling patterns**: Some functions throw, some return null, some return Result types — document the dominant pattern and flag deviations
+- **Async patterns**: Mixed callbacks/promises/async-await for the same kind of operation — modernize to the dominant (usually best) pattern
+- **String quotes**: Mixed single/double quotes (respect existing linter config if present)
+
+**Important**: Only fix inconsistencies where there's a clear "right way" already dominant in the codebase. Don't impose a new convention — reinforce the existing one. If it's genuinely 50/50, document it in the report and let the team decide.
+
+### Phase 4: Configuration & Feature Flag Hygiene
+
+This phase combines stale feature flag cleanup, TODO inventory, and comprehensive configuration hygiene.
+
+**Step 1: Feature flag inventory and cleanup**
+- Find every feature flag in the codebase (environment variables, config files, LaunchDarkly/Flagsmith/etc. references, hardcoded boolean switches)
+- For each flag, document:
+- Name and location
+- Current value (always true, always false, dynamic, or unknown)
+-  **Owner**: Who likely owns this flag? (Infer from git blame, module ownership, or comments)
+-  **Age**: When was it introduced? (Check git history)
+-  **Type**: Is this a temporary rollout flag, a permanent operational toggle, or a kill switch?
+- For always-true flags: remove the flag and keep the code
+- For always-false flags: remove the flag AND the dead code it guards
+-  For rollout flags older than 6 months that are always-on: these are almost certainly safe to remove. Remove the flag, keep the code.
+- Run tests after each removal. Commit: `chore: remove stale feature flag [name]`
+
+**Step 2: Flag coupling analysis**
+- Identify flags that depend on other flags (nested conditionals, compound flag checks)
+- Document the combinatorial complexity: how many distinct code paths do the current flags create?
+- Flag any combinations that are likely untested (e.g., if Flag A and Flag B are both "sometimes on," is the (A=true, B=false) path ever tested?)
+- Document these in the report — don't try to fix flag coupling overnight
+
+**Step 3: Configuration sprawl audit**
+- Find every configuration value in the codebase (constants, config files, environment variable reads, settings objects)
+- Identify configuration that is:
+- **Set but never varied**: Config values that have only ever been set to one value across all environments. These might be candidates for becoming constants.
+- **Undocumented**: Config values that have no comment, no README entry, and no `.env.example` entry explaining what they do or what valid values are
+- **Duplicated**: The same conceptual setting defined in multiple places (a timeout defined in both a config file and a hardcoded fallback, with different values)
+- **Unused**: Config values defined but never read by application code
+- For clearly unused config: remove it. Run tests. Commit: `chore: remove unused config [name]`
+- For undocumented config: add clear comments explaining what it controls, valid values, and default behavior
+- For duplicated config: consolidate to a single source of truth where safe
+
+**Step 4: Default value audit**
+- For every configuration value with a default, evaluate whether the default is appropriate:
+- Are there defaults appropriate for development that would be dangerous in production? (Debug mode on by default, permissive CORS by default, short token expiry in dev but what about prod?)
+- Are there defaults that silently degrade behavior? (A cache TTL defaulting to 0, effectively disabling caching)
+- Are there missing defaults that cause crashes if the config isn't explicitly set?
+- Document concerns in the report. Fix defaults that are clearly wrong and safe to change.
+
+**Step 5: TODO/FIXME/HACK inventory** (unchanged from original)
+- Find every TODO, FIXME, HACK, XXX, and TEMP comment in the codebase. For each one:
+- Categorize: bug, tech debt, feature request, optimization, or obsolete
+- If it's clearly obsolete (references old code that no longer exists, mentions completed work): remove it
+- For the rest: include in the report with file, line, category, and your assessment of priority
+
+### Phase 5: Quick Wins
+As you work through the phases above, you'll notice small improvements that don't fit neatly into a category. Fix them as you go:
+- Simplifying overly complex conditionals
+- Replacing deprecated API usage with modern equivalents
+- Removing unnecessary type assertions (TypeScript)
+- Converting var to const/let where applicable
+- Removing empty files, empty constructors, or no-op overrides
+- Fixing obvious typos in variable names or comments
+
+Commit these as `chore: misc cleanup in [module/file]`
+
+## Output Requirements
+
+Create the `audit-reports/` directory in the project root if it doesn't already exist. Save the report as `audit-reports/10_CODEBASE_CLEANUP_REPORT_[run-number]_[date]_[time in user's local time].md` (e.g., `10_CODEBASE_CLEANUP_REPORT_01_2026-02-16_2129.md`). Increment the run number based on any existing reports with the same name prefix in that folder.
+
+### Report Structure
+
+1. **Summary**
+- Total files modified
+- Lines of code removed (net)
+- Unused dependencies removed
+- Number of commits made
+- Any tests that were affected
+
+2. **Dead Code Removed** — list everything you removed and why you're confident it was dead
+
+3. **Duplication Reduced** — what you consolidated, plus higher-risk duplications you documented but didn't touch
+
+4. **Consistency Changes** — what patterns you enforced and where
+
+5. **Configuration & Feature Flags**  (expanded from original)
+- Flags removed: table with | Flag | Type | Age | Value | Action Taken |
+-  Flag coupling map (which flags interact and the combinatorial paths created)
+-  Configuration sprawl findings: table with | Config | Location | Issue | Action |
+-  Default value concerns: table with | Config | Default | Concern | Recommendation |
+- Full TODO/FIXME inventory table: | File | Line | Comment | Category | Priority | Recommendation |
+
+6. **Couldn't Touch** — things you wanted to fix but couldn't because:
+- Tests broke when you tried
+- The change was too risky without team input
+- You weren't sure about the intended behavior
+
+7. **Recommendations** — larger refactoring opportunities you noticed that deserve their own effort
+
+## Rules
+- Branch: `codebase-cleanup-[date]`
+- Run tests after EVERY change. No exceptions.
+- If tests fail, revert immediately and document why
+- Make small, atomic commits — one logical change per commit
+- Commit messages should start with `chore:` and clearly describe what was done
+- DO NOT change any business logic. If you're unsure whether something is dead code or intentional, leave it and document it
+- DO NOT refactor working code just because you'd write it differently. Only fix actual issues: dead code, duplication, inconsistency.
+- When in doubt, document rather than change. Conservative changes that keep tests green are infinitely more valuable than aggressive changes that might break things.
+- You have all night. Be thorough. Check every directory.
+```
+
+## Chat Output Requirement
+
+In addition to writing the full report file, you MUST print a summary directly in the conversation when you finish. Do not make the user open the report to get the highlights. The chat summary should include:
+
+### 1. Status Line
+One sentence: what you did, how long it took, and whether all tests still pass.
+
+### 2. Key Findings
+The most important things discovered — bugs, risks, wins, or surprises. Each bullet should be specific and actionable, not vague. Lead with severity or impact.
+
+**Good:** "CRITICAL: No backup configuration found for the primary Postgres database — total data loss risk."
+**Bad:** "Found some issues with backups."
+
+### 3. Changes Made (if applicable)
+Bullet list of what was actually modified, added, or removed. Skip this section for read-only analysis runs.
+
+### 4. Recommendations
+
+If there are legitimately beneficial recommendations worth pursuing right now, present them in a table. Do **not** force recommendations — if the audit surfaced no actionable improvements, simply state that no recommendations are warranted at this time and move on.
+
+When recommendations exist, use this table format:
+
+| # | Recommendation | Impact | Risk if Ignored | Worth Doing? | Details |
+|---|---|---|---|---|---|
+| *Sequential number* | *Short description (≤10 words)* | *What improves if addressed* | *Low / Medium / High / Critical* | *Yes / Probably / Only if time allows* | *1–3 sentences explaining the reasoning, context, or implementation guidance* |
+
+Order rows by risk descending (Critical → High → Medium → Low). Be honest in the "Worth Doing?" column — not everything flagged is worth the engineering time. If a recommendation is marginal, say so.
+
+### 5. Report Location
+State the full path to the detailed report file for deeper review.
+
+---
+
+**Formatting rules for chat output:**
+- Use markdown headers, bold for severity labels, and bullet points for scannability.
+- Do not duplicate the full report contents — just the highlights and recommendations.
+- If you made zero findings in a phase, say so in one line rather than omitting it silently.

package/src/prompts/steps/11-crosscutting-concerns.md

@@ -0,0 +1,196 @@
+# Cross-Cutting Concerns Consistency Audit
+
+Find patterns that should be identical across the codebase but have drifted. Other audits check within a single module; this one checks each pattern **across every instance, file, and layer** — drift between implementations is the bug.
+
+Branch: `cross-cutting-consistency-[date]`. Report: `audit-reports/11_CROSS_CUTTING_CONSISTENCY_REPORT_[run-number]_[date]_[time in user's local time].md`.
+
+---
+
+## Global Rules
+
+- Run tests after every change. Commits: `fix: standardize [pattern] in [module]`
+- Per concern: **(1)** find every instance, **(2)** identify dominant/best pattern, **(3)** catalog every deviation, **(4)** fix only mechanical low-risk deviations, **(5)** document everything else.
+- **Only fix** when: canonical pattern is unambiguous, change is mechanical (not behavioral), code has test coverage, no API contract or user-facing behavior changes.
+- **Do NOT fix**: public endpoint response shapes, business logic, untested code, or 50/50 splits (document both, recommend team decision).
+- **Be exhaustive.** "37 of 40 endpoints use offset/limit, 3 use cursor-based" is valuable. "Most use offset/limit" is not. Count everything.
+- For multi-tenancy and soft-delete: missing filters = potential data leak bugs. Treat as security-severity.
+
+---
+
+## Phase 1: Pagination Consistency
+
+Find every list/collection endpoint, query, UI list, and GraphQL connection. For each, catalog:
+
+- **Strategy**: offset/limit, page/pageSize, cursor-based, keyset, or unbounded
+- **Param names**: `page`/`limit`/`per_page`/`pageSize`/`cursor`/`after`/`next_token`/etc.
+- **Defaults & max page size** (flag missing maximums)
+- **Response metadata shape**: `{ total, page, pageSize }` vs `{ totalCount, hasMore, nextCursor }` vs wrapped vs none
+- **Where logic lives**: handler, service, shared utility, ORM scope, inline
+- **Edge cases**: page 0 vs 1, negative, beyond total, pageSize=0, pageSize=999999
+
+**Safe fixes**: Add missing max page size limits. Align internal param names. Standardize metadata on internal endpoints. Add missing defaults.
+
+**Report table**: Location | Type | Strategy | Params | Defaults | Max Size | Metadata Shape | Canonical? | Fixed?
+
+---
+
+## Phase 2: Sorting & Filtering Consistency
+
+Find every sortable/filterable endpoint or dynamic query. Catalog:
+
+- **Sort format**: `?sort=name` vs `?sort_by=name&order=asc` vs `?sort=name:asc` vs others
+- **Multi-field sort** support and syntax
+- **Default sort** (explicit or implicit insertion order = fragile)
+- **Filter format**: `?status=active` vs `?filter[status]=active` vs others
+- **Filter operators**: equality only or range/contains/in? Consistent syntax?
+- **Search**: `?q=` vs `?search=` vs `?query=` — type (full-text, LIKE, regex) and which fields
+- **Validation**: sort fields checked against allowlist? (Flag missing allowlists)
+- **SQL injection risk**: dynamic fields parameterized or concatenated? (**CRITICAL** if concatenated)
+
+**Safe fixes**: Standardize internal param names. Add missing sort field allowlists. Add default sorts. Fix SQL injection risks.
+
+**Report table**: Location | Sort Format | Filter Format | Search Format | Default Sort | Validated? | Canonical?
+
+---
+
+## Phase 3: Soft Delete & Data Lifecycle Consistency
+
+Find every deletion operation (DELETE queries, `.destroy()`/`.delete()`, status→deleted/archived, `deleted_at`/`is_deleted` updates, hard deletes). Catalog:
+
+- **Strategy**: hard delete, soft delete (timestamp vs boolean vs status-based), or mixed
+- **Field used**: `deleted_at` vs `deletedAt` vs `is_deleted` vs `status` vs `active` (inverted)
+- **Query filtering**: do ALL read queries on soft-delete tables exclude deleted records? (Missing filters = silent data integrity bugs)
+- **Unique constraints**: can soft-deleted records block new records with same unique field?
+- **Cascade**: parent soft-deleted → children soft-deleted? hard-deleted? orphaned?
+- **Restoration path**, permanent purge process
+- **API behavior**: DELETE returns what? GET on deleted record returns 404, 410, or flagged record?
+
+**Most dangerous drift**: some queries filtering soft-deleted records, others not.
+
+**Safe fixes**: Add missing `WHERE deleted_at IS NULL`. Standardize field names via migration files (don't run).
+
+**Report table**: Entity | Strategy | Field | All Queries Filter? | Cascade | Unique Constraint Issue? | Restoration? | Purge?
+
+---
+
+## Phase 4: Audit Logging & Activity Tracking Consistency
+
+Find every audit mechanism (audit tables, activity feeds, event tracking, `created_by`/`updated_by` fields, timestamps, change history, webhooks). For every create/update/delete on every significant entity, catalog:
+
+- **Is it logged?** Via what mechanism?
+- **What's captured?** Actor, action, target, timestamp, before/after values, IP/session context
+- **Where logged?** Inline, middleware, ORM hook, DB trigger, event subscriber
+- **Storage & retention**
+
+**Flag operations with no audit trail**, especially: user data changes, permission/role changes, financial ops, admin actions, auth events, data exports, config changes, deletions.
+
+**Safe fixes**: Add missing `updated_at` auto-update. Populate `created_by`/`updated_by` where pattern exists but was missed. Add audit entries for unlogged critical ops using existing mechanism. Do NOT introduce new audit mechanisms.
+
+**Report table**: Entity | Create Logged? | Update Logged? (diff?) | Delete Logged? | Actor Captured? | Mechanism | Gaps
+
+---
+
+## Phase 5: Timezone & Date/Time Handling Consistency
+
+Find every date/time operation (creation, parsing, formatting, storage, comparison, arithmetic, timezone conversion, display). Catalog:
+
+- **Storage TZ**: UTC, server-local, user-local, mixed? Column types: `TIMESTAMP` vs `TIMESTAMPTZ` vs `DATETIME` vs `VARCHAR`?
+- **Library**: `Date`, `moment`, `date-fns`, `dayjs`, `luxon` — multiple in use?
+- **Server-side creation**: `new Date()` (server TZ), `Date.now()`, `moment.utc()`, DB `NOW()`?
+- **User display**: converted to user TZ? Where does user TZ come from?
+- **API format**: ISO 8601? Unix timestamps? Locale strings? Mixed?
+- **Date-only values**: stored as datetime (midnight of which TZ?), date type, or string?
+- **DST handling**: adds 24 hours (wrong) or 1 calendar day (right)?
+- **Date boundaries**: "today's records" — whose today?
+
+**Dangerous drift**: some DB columns UTC, others server-local (invisible until multi-zone or DST). Mixed API date formats.
+
+**Safe fixes**: Replace `new Date()` with UTC equivalents per convention. Standardize internal API dates to ISO 8601. Add TZ-aware column types in migration files. Replace deprecated date library usage.
+
+**Report table**: Location | Operation | Library | Timezone | Format | Storage Type | Canonical? | Risk
+
+---
+
+## Phase 6: Currency & Numeric Precision Consistency
+
+**Skip if app doesn't handle money/prices/precision-sensitive numbers. State why.**
+
+Find every monetary/precision operation. Catalog:
+
+- **Storage**: integer cents, `DECIMAL(x,y)`, `FLOAT`, string?
+- **Code representation**: float, BigDecimal, integer cents, money library?
+- **Arithmetic**: float math (precision loss), integer math (truncation), library-based?
+- **Rounding**: method and consistency
+- **Currency**: hardcoded, per-record, configurable?
+- **Display & API format**: consistent?
+
+**Dangerous drift**: mixing float and integer cents (off-by-one-cent bugs at scale).
+
+**Report table**: Location | Value Type | Storage | Code Rep | Arithmetic | Rounding | Display | Canonical? | Precision Risk?
+
+---
+
+## Phase 7: Multi-Tenancy & Data Isolation Consistency
+
+**Skip if single-tenant with no org/workspace/team concept. State why.**
+
+Identify tenancy model (row-level `tenant_id`, schema-per-tenant, etc.). For every query, endpoint, and background job, audit:
+
+- **Tenant scoping applied?** Via middleware (automatic) or manual per-query?
+- **Bypassable?** Can developers write unscoped queries?
+- **Background jobs**: receive and enforce tenant context?
+- **Caches, file storage, search indexes**: tenant-scoped?
+- **Unique constraints**: scoped to tenant?
+
+**Missing tenant scoping on user-data table = CRITICAL cross-tenant data exposure.**
+
+**Report table**: Entity | Has tenant_id? | Scoping Method | All Queries Scoped? | Cache Scoped? | Files Scoped? | Gaps
+
+---
+
+## Phase 8: Error Response & Status Code Consistency
+
+For each scenario below, find every occurrence across all endpoints and compare responses:
+
+**Scenarios**: Validation failure (400 vs 422, shape), Not found (404), Not authorized (401 vs 403), Forbidden, Conflict/duplicate (409 vs 400), Rate limited (429 + headers), Internal error (500, detail leakage), Method not allowed (405), Request too large (413)
+
+For each: catalog dominant response, deviations (with location), and whether deviation is intentional.
+
+**Safe fixes**: Align error responses on internal endpoints to dominant pattern.
+
+**Report table per scenario**: Endpoint | Status Code | Response Shape | Message | Canonical? | Fixed?
+
+---
+
+## Phase 9: Synthesis & Drift Map
+
+### Drift Heat Map
+Rate each concern: **Consistent** (90%+), **Minor drift** (70-90%), **Significant drift** (50-70%), **No standard** (<50%).
+
+### Root Cause Analysis
+Per area with significant drift: missing shared utility? Convention changed over time? Different developer conventions? Pattern never decided?
+
+### Prevention Recommendations
+Per concern: shared utility to build, linter rule to enforce, code review checklist item, documentation to write.
+
+---
+
+## Chat Output Requirement
+
+Print a summary in conversation (don't make user open the report):
+
+1. **Status Line** — What you did, whether tests pass.
+2. **Key Findings** — Specific, actionable bullets with severity. Lead with impact.
+- ✅ "CRITICAL: 4 of 22 queries on `orders` don't filter `deleted_at` — soft-deleted orders appear in invoices."
+- ❌ "Found some inconsistencies with soft deletes."
+3. **Changes Made** (if any) — Bullet list. Skip for read-only runs.
+4. **Drift Heat Map** — Summary table from report.
+5. **Recommendations** — Table (only if warranted):
+
+| # | Recommendation | Impact | Risk if Ignored | Worth Doing? | Details |
+|---|---|---|---|---|---|
+| *n* | *≤10 words* | *What improves* | *Low/Med/High/Critical* | *Yes/Probably/Only if time* | *1–3 sentences* |
+
+Order by risk descending. Be honest in "Worth Doing?" — not everything is worth the engineering time.
+
+6. **Report Location** — Full path to detailed report.