Walkthrough

The PR updates pre-commit-related schema, tests, and formatting; changes MkDocs publishing and build behavior; adds CI shard coverage for Explainer tests; and records the work in new backlog task documents.

Changes

Post-PR-1982 Pre-commit Fixes

MkDocs Deploy Verification Fix

CI Shard Coverage Update

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped through checks and tidy lines,
Wove docs and shards in careful signs.
A key was masked, a build path stayed,
And rabbit notes were neatly laid.
Three little trails now run in tune,
Under the bright PR-review moon.

❌ Failed checks (1 warning)

• Apply EOF/trailing-whitespace/Black fixes to resolve post-merge pre-commit failures.
• Rework PEM-like secret markers in tests to satisfy detect-private-key without reducing redaction
 coverage.
• Update onboarding UAT hosted fixture expectation to match auth-enabled configuration.

graph TD
  CI["Pre-commit CI"] --> Hooks["Hooks (EOF/Black/secrets)"] --> Docs["Docs & backlog"]
  Hooks --> Backend["tldw_Server_API"] --> PyTests["Pytest fixtures"]
  Hooks --> Frontend["tldw-frontend"] --> Vitest["Vitest UAT tests"]

Loading

The following are alternative approaches to this PR:

1. Allowlist/ignore test fixtures in detect-private-key

• ➕ Simplest code changes in tests (keep literal PEM strings).
• ➕ Centralized configuration for future fixtures.
• ➖ Weakens the guardrail by exempting paths/markers where leaks can still occur.
• ➖ Requires ongoing maintenance as paths/tests change.

2. Encode the key-like marker and decode at runtime

• ➕ Avoids triggering secret detectors while keeping deterministic runtime content.
• ➕ Keeps test intent clear if wrapped with helper utilities.
• ➖ More indirection than simple string concatenation.
• ➖ Can be misread as attempting to conceal real secrets if not documented.

3. Use non-PEM-shaped sentinel strings for redaction tests

• ➕ Avoids any secret-scanner heuristics entirely.
• ➕ Keeps tests simple.
• ➖ Reduces realism/coverage for PEM/SSH-key specific redaction patterns.
• ➖ May miss regressions in logic tuned for real key headers/footers.

Recommendation: Keep the PR’s approach: split the PEM-like markers via string concatenation at runtime. It satisfies detect-private-key while preserving realistic secret shapes for redaction/leak coverage, without introducing repo-wide exemptions or degrading test fidelity.

Refactor (8) +14 / -20

CodeBlock.tsxRemove trailing whitespace and normalize formatting +7/-7

Remove trailing whitespace and normalize formatting

• Cleans up whitespace-only diffs and normalizes formatting to satisfy frontend lint/format hooks.

apps/packages/ui/src/components/Common/CodeBlock.tsx

types.tsRemove trailing whitespace in type definition +1/-1

Remove trailing whitespace in type definition

• Fixes a trailing-space issue in the SessionFiles type so formatting hooks pass.

apps/packages/ui/src/db/dexie/types.ts

useShortcutConfig.tsRemove stray whitespace in shortcut formatter +3/-3

Remove stray whitespace in shortcut formatter

• Normalizes whitespace in formatShortcut to satisfy formatting checks without functional changes.

apps/packages/ui/src/hooks/keyboard/useShortcutConfig.ts

audio_health.pyRemove trailing blank line at EOF +0/-1

Remove trailing blank line at EOF

• Removes a trailing blank line to satisfy end-of-file/whitespace checks; no schema behavior changes.

tldw_Server_API/app/api/v1/schemas/audio_health.py

db_adapter.pyRemove stray whitespace before transaction context manager +1/-1

Remove stray whitespace before transaction context manager

• Eliminates whitespace-only indentation/trailing-space noise to satisfy formatting hooks.

tldw_Server_API/app/core/Evaluations/db_adapter.py

exceptions.pyRemove trailing blank line at EOF +0/-1

Remove trailing blank line at EOF

• Removes an extra trailing blank line to satisfy end-of-file checks.

tldw_Server_API/app/core/Sandbox/exceptions.py

profile_verify.pyBlack-format first_chat_completed expression +1/-3

Black-format first_chat_completed expression

• Collapses a parenthesized multi-line boolean assignment into a single line consistent with Black formatting (no intended behavior change).

tldw_Server_API/cli/wizard/profile_verify.py

profiles.pyBlack-format docker/webui env assignment +1/-3

Black-format docker/webui env assignment

• Collapses a multi-line env assignment into a single line consistent with Black formatting (no intended behavior change).

tldw_Server_API/cli/wizard/profiles.py

Tests (3) +10 / -12

onboarding-uat-runner.test.tsAvoid private-key detection and update hosted auth assertion +4/-3

Avoid private-key detection and update hosted auth assertion

• Builds the private-key marker via runtime concatenation to avoid detect-private-key false positives while keeping leak checks meaningful. Updates the hosted-success fixture expectation to require auth (require_auth=true).

apps/tldw-frontend/scripts/tests/onboarding-uat-runner.test.ts

test_acp_hardening_helpers.pyConstruct SSH private key headers/footers at runtime in redaction test +4/-2

Construct SSH private key headers/footers at runtime in redaction test

• Splits the OpenSSH private key header/footer via concatenation and uses them in the test input to avoid secret-scanner false positives while still exercising redaction behavior.

tldw_Server_API/tests/Agent_Client_Protocol/test_acp_hardening_helpers.py

test_cli_verify_profiles.pyBlack-format test signature and assertion +2/-7

Black-format test signature and assertion

• Reformats the test function signature and converts a multi-line containment assert into a single-line assert for formatter compliance.

tldw_Server_API/tests/wizard/test_cli_verify_profiles.py

Documentation (14) +84 / -31

Watchlists_API.mdRemove trailing whitespace in filter types line +1/-1

Remove trailing whitespace in filter types line

• Fixes a trailing-space violation in the Filter types line to satisfy whitespace/EOF pre-commit hooks.

Docs/API-related/Watchlists_API.md

Evals.mdAdd missing newline at EOF +1/-1

Add missing newline at EOF

• Adds a trailing newline so the file complies with end-of-file fixer checks.

Docs/Design/Evals.md

Sandbox.mdNormalize header/links and trim trailing lines +8/-16

Normalize header/links and trim trailing lines

• Removes trailing spaces, normalizes link formatting, and deletes extra blank lines at the end to satisfy pre-commit formatting rules.

Docs/Design/Sandbox.md

Security.mdAdd missing newline at EOF +1/-1

Add missing newline at EOF

• Adds a trailing newline to satisfy end-of-file fixer checks.

Docs/Design/Security.md

tldw_web_design_system_inventory.mdFix trailing whitespace in anchor path list +2/-2

Fix trailing whitespace in anchor path list

• Removes trailing spaces from two list entries to comply with whitespace checks.

Docs/Design/tldw_web_design_system_inventory.md

CodeGraph.mdTrim trailing blank line at EOF +0/-1

Trim trailing blank line at EOF

• Removes an extra trailing blank line to satisfy end-of-file/whitespace pre-commit hooks.

Docs/MCP/Unified/CodeGraph.md

Watchlists_API.mdRemove trailing whitespace in published watchlist docs +1/-1

Remove trailing whitespace in published watchlist docs

• Applies the same trailing-space fix as the source Watchlists API doc to keep published docs compliant.

Docs/Published/API-related/Watchlists_API.md

WORKSPACE_PLAYGROUND_A11Y_CONTRAST_AUDIT_2026_02_18.mdNormalize date line and remove trailing blank line +1/-2

Normalize date line and remove trailing blank line

• Removes trailing whitespace from the Date line and trims a trailing blank line to satisfy pre-commit checks.

Docs/Reviews/WORKSPACE_PLAYGROUND_A11Y_CONTRAST_AUDIT_2026_02_18.md

puppeteer-p1-smoke.jsonAdd newline at EOF +1/-1

Add newline at EOF

• Adds a final newline so the JSON fixture passes end-of-file fixer validation.

Docs/Reviews/assets/2026-05-09-character-chat-p1-smoke/puppeteer-p1-smoke.json

puppeteer-states.jsonAdd newline at EOF +1/-1

Add newline at EOF

• Adds a final newline so the JSON fixture passes end-of-file fixer validation.

Docs/Reviews/assets/2026-05-09-character-chat-reaudit/puppeteer-states.json

Writing_Characters.mdAdd missing newline at EOF +1/-1

Add missing newline at EOF

• Adds a trailing newline at the end of the user guide so it passes EOF checks.

Docs/User_Guides/Writing_Characters.md

2026-05-26-research-workspace-mcp-hub-deep-link-design.mdTrim trailing blank line at EOF +0/-1

Trim trailing blank line at EOF

• Removes an extra trailing blank line to satisfy end-of-file/whitespace hooks.

Docs/superpowers/specs/2026-05-26-research-workspace-mcp-hub-deep-link-design.md

Research-Workspace-UAT-Remediation.mdRemove trailing blank lines from milestone frontmatter +0/-2

Remove trailing blank lines from milestone frontmatter

• Trims trailing blank lines after frontmatter to satisfy whitespace/EOF checks.

backlog/milestones/Research-Workspace-UAT-Remediation.md

task-12073 - Fix-post-PR-1982-main-pre-commit-failure.mdAdd task record for post-PR-1982 pre-commit remediation +66/-0

Add task record for post-PR-1982 pre-commit remediation

• Introduces a backlog task entry documenting the files touched and the final verification summary for the remediation work.

backlog/tasks/task-12073 - Fix-post-PR-1982-main-pre-commit-failure.md

Other (1) +0 / -1

py.typedNormalize py.typed marker file content +0/-1

Normalize py.typed marker file content

• Removes the file’s lone placeholder line so the typing marker is clean and hook-compliant (empty marker file).

apps/mcp-unified/src/mcp_unified/py.typed

Description

The modified test test_profile_checks_report_first_chat_state_without_completing_setup has no
required pytest marker (unit/integration/external_api/local_llm_service). This violates the
project requirement for explicit test categorization and can break marker-gated CI runs.

Code

tldw_Server_API/tests/wizard/test_cli_verify_profiles.py[453]

+def test_profile_checks_report_first_chat_state_without_completing_setup(monkeypatch, tmp_path: Path) -> None:

Evidence

PR Compliance ID 380651 requires exactly one approved pytest marker on each new/modified test. The
changed test definition at the cited lines has no @pytest.mark.* decorator (and there is no
module-level pytestmark in this file).

Rule 380651: Apply appropriate pytest markers to all tests
tldw_Server_API/tests/wizard/test_cli_verify_profiles.py[453-453]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A modified pytest test function is missing the required marker decorator.

## Issue Context
Compliance requires each new/modified test to be marked with exactly one of: `@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.external_api`, or `@pytest.mark.local_llm_service`. The changed test currently has no marker and the module also does not import `pytest`.

## Fix Focus Areas
- tldw_Server_API/tests/wizard/test_cli_verify_profiles.py[453-453]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools