Research: Local Document Router W-9 index-miss — critique, patch, and tests

We are building a private local Document Router for my own Mac and business files. I need you to help solve one specific engineering problem, not redesign the whole system.

Current architecture:

• ChatGPT = command center / reasoning

• Hermes + local agent = persistent local execution

• Mac local search scope = ~/Desktop, ~/Downloads, ~/Documents

• Dainty business identities:

  • legal entity: DAINTY SOLUTIONS GROUP LLC
  • DBA: Dainty Touch Estate Solutions

Problem: A local indexed search returned zero results for a W-9 that definitely existed in Downloads. Direct directory inspection found:

• IRS_Form_W-9_Rev_December_2014.pdf
• IRS_Form_W-9_Rev_December_2014 (1).pdf
• VendorLinkFile.xlsx
• VendorLinkZipFile.zip

The correct system behavior should be:

1. Search Desktop → Downloads → Documents.
2. Never treat a single indexed-search miss as authoritative when workflow context strongly suggests the document exists.
3. Expand the search using filename variants, canonical form/document language, legal entity/DBA names, workflow terms, vendor/platform names, related artifacts, timestamps, and co-location.
4. Fall back to direct directory enumeration when the index misses.
5. Inspect candidate content safely.
6. Rank candidates by entity match, workflow fit, populated-vs-template indicators, recency, and nearby related files.
7. Never expose or log SSN/EIN/TIN values.

I already have a rough Node.js inspector prototype using fs, path, and pdf-parse.

Your job:

• Critique the architecture and prototype only where technically necessary.

• Identify concrete failure modes or bugs.

• Recommend the smallest production-ready implementation.

• Give exact code changes or a replacement implementation where needed.

• Include tests for:

  • indexed search miss
  • fallback direct enumeration
  • W-9 candidate near VendorLink artifacts

• completed business form ranking above blank/template

• no sensitive tax values in logs/output

• symlink/path traversal protection

• fair searching of all three roots so Desktop cannot consume the entire candidate cap

Do not suggest public GitHub issues, cloud architecture, or unrelated redesigns.

Return only:

1. Critical defects
2. Recommended implementation
3. Code/patch
4. Acceptance tests
5. Anything that would block production use

Bring me what it gives you. I’ll extract the useful engineering pieces, reject anything that doesn’t fit our architecture, and turn the result into the next implementation step.