fix: document direct database query exceptions

[chubes4]

Summary

• Adds documented direct-database-query exceptions for Data Machine-owned operational tables where WordPress APIs do not exist and fresh runtime state is required.
• Keeps direct database lint scopes from being re-enabled inside nested prepared-SQL suppression blocks.
• Clears the Plugin Check direct_db_queries findings for the audited worktree.

Verification

• studio wp plugin check /Users/chubes/Developer/data-machine@issue-21-db-query-caching --checks=direct_db_queries --format=csv --fields=file,line,code --include-experimental
• composer lint
• composer test (1288 tests, 1285 passed, 3 skipped)

Closes #21

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (openai/gpt-5.5)
• Used for: Re-audited Plugin Check findings, applied the direct database query exception annotations, and ran local verification. Chris remains responsible for review and merge.

[homeboy-ci]

Homeboy Results — data-machine

Lint

✅ lint — passed

ℹ️ Full options: homeboy docs commands/lint
Deep dive: homeboy lint data-machine --changed-since 165c424

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-data-machine-lint-quality-Linux-node24 contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-data-machine-lint-quality-Linux-node24 contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/data-machine/actions/runs/26315884843

Test

✅ test — passed

• 33 passed

ℹ️ Auto-fix lint issues: homeboy refactor data-machine --from lint --write
ℹ️ Collect coverage: homeboy test data-machine --coverage
ℹ️ Save test baseline: homeboy test data-machine --baseline
ℹ️ Pass args to test runner: homeboy test -- [args]
ℹ️ Full options: homeboy docs commands/test
Deep dive: homeboy test data-machine --changed-since 165c424

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-data-machine-test-quality-Linux-node24 contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-data-machine-test-quality-Linux-node24 contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/data-machine/actions/runs/26315884843

Audit

✅ audit — passed

• requested_detectors — 247 finding(s)
• dead_code — 171 finding(s)
• intra-method-duplication — 98 finding(s)
• repeated_literal_shape — 17 finding(s)
• field_patterns — 9 finding(s)
• structural — 7 finding(s)
• Api — 6 finding(s)
• Abilities — 5 finding(s)
• Taxonomy — 5 finding(s)
• parallel-implementation — 5 finding(s)
• Total: 586 finding(s)

Deep dive: homeboy audit data-machine --changed-since 165c424

Artifacts and drill-down

• CI results artifact: homeboy-ci-results-data-machine-audit-quality-Linux-node24 contains immediate command JSON for this action invocation.
• Observation artifact: homeboy-observations-data-machine-audit-quality-Linux-node24 contains exported Homeboy run history for deeper queries.
• Drill-down: download the observation artifact, then run homeboy runs import <dir>, homeboy runs list, and homeboy runs findings <run-id>.
• Artifacts are attached to the workflow run: https://github.com/Extra-Chill/data-machine/actions/runs/26315884843

Tooling versions

• Homeboy CLI: homeboy 0.197.2+1d49743b
• Extension: wordpress from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: dd23ee80
• Action: unknown@unknown