GW-031: Complete full doctor and data doctor

[trippyogi]

Outcome

Expand doctor into a complete capability and local-data diagnostic that tells a user or agent exactly which Gitworthy workflows are safe to run, which will be degraded, and how to fix each problem.

Add both environment/provider checks and a data doctor path for the versioned local store, migrations, indexes, captures, and disk health.

Why this matters

Agent workflows fail in confusing ways when auth scopes, timeline visibility, git, npm, cache, disk, or local data are partially available. A single overall sentence is not enough; the host agent needs a machine-readable capability matrix and actionable remediation before starting a hunt.

Scope

• Report Node and git versions.
• Report GitHub token presence, authenticated identity, relevant rate limits, and timeline cross-reference capability.
• Use a controlled known fixture for capability probes; report inconclusive rather than inferring from an arbitrary quiet issue.
• Check GitHub API, npm registry, safe ls-remote, cache directory, data directory, schema/migration state, index integrity, disk space where available, and installed versus published package version.
• Add optional full safe-clone, package-smoke, and MCP list/call self-tests for release validation.
• Add data doctor checks for corrupt/quarantined records, stale locks, rebuildable indexes, migration markers, unsupported versions, and capture safety.
• Return each capability as pass, warn, fail, or skipped with one remediation.
• Support human and structured output with CLI/MCP parity for read-only checks.

Non-goals

• No automatic destructive repair.
• No broad network benchmark.
• No requirement for every optional capability to pass before basic public checks.
• No token printing or secret diagnostics.

Dependencies and readiness

• Depends on GW-011 / issue GW-011: Add bounded HTTP client, retries, pagination, request budgets #20, completed by PR 0.4.0: bounded shared HTTP client for GitHub (GW-011) #51.
• Depends on GW-016 / issue GW-016: Add safe legacy-ledger migration, quarantine, and index rebuild #25, completed by PR 0.5.0: legacy ledger migration + index rebuild (GW-016) #61.
• Contributor readiness: READY. Coordinate output rendering with GW-030 and MCP annotations with GW-032.

Acceptance criteria

• Doctor returns a versioned capability matrix rather than only an overall summary.
• Every failed/warned capability has an actionable remediation.
• Timeline visibility uses a controlled fixture or reports inconclusive honestly.
• Data doctor validates schemas, indexes, migration status, locks, quarantine, and rebuildability without losing data.
• Standard doctor performs no destructive mutation.
• Full mode can exercise safe clone, packed package, and MCP self-test for release validation.
• Auth/rate details are useful but redact all credentials.
• Exit behavior distinguishes pass, warning/VERIFY, invalid invocation, and operational failure.
• Human and JSON output are documented and stable.

Tests and validation

• Pass/warn/fail/skipped fixtures for every capability.
• Missing token, weak token scope, low rate limit, offline provider, missing git, old Node, unwritable cache/data, low disk, corrupt index, stale lock, and unsupported schema cases.
• Controlled timeline fixture success and inconclusive behavior.
• Data doctor proves index rebuild recommendation without silently mutating.
• Secret-redaction and stdout/stderr tests.
• Packed-package and MCP self-test in release CI.

Likely implementation areas

• src/core/doctor.ts capability checks.
• Store/data inspection helpers.
• Controlled provider fixtures.
• CLI/MCP contracts and rendering.
• Release-validation scripts.

Compatibility and safety

Preserve existing doctor fields during migration where practical. Repair actions must be separate explicit commands, support dry-run, and never treat malformed data as an empty store.

[trippyogi]

Shipped initial capability matrix + data-store doctor checks in #75. Remaining AC items (full mode pack/MCP self-test, broader fixtures, packed release doctor) stay open.