doctor-link 0.5.0

Universal diagnostic and AI collaboration tool for software debugging.

Doctor link

Doctor link is a local-first, human-AI shared diagnostic and verified-repair layer for software projects.

Doctor link 是一个本地优先、面向软件项目的人机协同诊断与修复验收层。它不仅组织问题、证据和 AI 上下文，还能在明确授权后驱动 Codex 修复 Python 或 Node.js JavaScript/TypeScript 项目，并独立重测是否真正解决。

• English documentation
• 中文文档
• GitHub repository guide

Why Doctor link

AI coding tools can edit code quickly, but they still need reliable context. Doctor link helps a person and an AI tool agree on:

• what the problem is;
• which evidence supports it;
• which claims came from a human;
• which commands reproduced the behavior;
• what changed before and after a fix;
• which checks are required before closure.

Doctor link does not replace Codex, Cursor, Aider, OpenHands, Continue, Cline, Windsurf, or similar tools. It prepares a structured, privacy-aware diagnostic package that those tools can consume.

Verified status

Latest published version: v0.4.0, published on 2026-07-14.

Version v0.4.0 adds workspace package targeting, interrupted-session recovery, and multi-project solve benchmarks. It passed 349 tests at 85.15% branch-aware coverage, a 64-route installed-wheel lab, and a live protected-contract monorepo repair. PR #149 merged as 9e83e96; release workflow 29303850286 published the immutable tag and assets with PyPI disabled.

The current v0.5.0 source adds natural-language reproduction discovery, a guided doctor-link assist entrypoint with a local browser result, and a 24-project Python/Node.js benchmark corpus.

The verified automatic problem-solving release in PR #145 passed the complete repository validation matrix on 2026-07-13:

• 319 automated tests;
• 85.39% branch-aware coverage with an enforced 85% floor;
• Python 3.10, 3.11, and 3.12;
• Ubuntu, macOS, and Windows smoke validation;
• Ruff, Bandit, and dependency vulnerability checks;
• wheel and source-distribution build, content inspection, Twine validation, and isolated installation;
• E2E, self-validation, project validation, and P7 runtime validation;
• all 63 public CLI routes through 71 real installed-package invocations and nine complex scenarios.

Evidence:

• 100/100 repository-readiness scorecard
• cloud validation certificate
• validation evidence index
• v0.2.0 final PR CI
• v0.2.0 Release workflow

PR #145 was merged as commit 40a547c, and the authorized GitHub Release v0.2.0 was published by release workflow 29256955705. The workflow installed the final wheel, reran the full capability lab, and created an immutable tag before uploading both distributions. PyPI publication was disabled and was not performed.

Main capabilities

Capability	What it provides
Preflight	Read-only inspection of project configuration, commands, catalogs, Python version, and local tools.
Diagnostic packages	Structured reports, summaries, evidence indexes, timelines, problem maps, and machine-readable JSON.
Evidence collection	Logs, attachments, environment metadata, command results, redaction records, and integrity indexes.
Human assertions	Explicit records of user-confirmed problems that AI output must not silently dismiss.
Reproduction and tests	Shell-free configured command execution, test matrices, evidence write-back, and timeout metadata.
Guided problem solving	Ordinary-language problem matching, ranked safe reproduction checks, local browser results, and repair preview without requiring test-command knowledge.
Automatic solve	Python and Node.js JavaScript/TypeScript failure reproduction, explicit repair approval, isolated Git branch, bounded Codex rounds, protected verification inputs, and independent regression acceptance.
Verification	Missing-evidence reporting, linked assertion coverage, failed-test blockers, before/after comparison, and conservative closure status.
AI handoff	Tool-specific packages with explicit repair, evidence, and verification-review readiness states.
Local workbench	Static local HTML for reviewing diagnostic packages without a hosted service.
Security and privacy	Redaction, privacy scanning, export gates, integrity manifests, and explicit execution approval.
Extensibility	Adapter and plugin manifests with dry-run defaults, permission checks, and audit records.
Operations	CI reports, project health, local knowledge indexes, archives, and distribution readiness.

Quick start

Requirements: Git and Python 3.10 or later.

git clone https://github.com/linkyang01/doctor-link.git
cd doctor-link
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
doctor-link --version
doctor-link preflight . --json

For the simplest path, describe the problem and let Doctor link find and validate a reproduction:

doctor-link assist /path/to/project --problem "Checkout duplicates a charge"

On Windows PowerShell, activate the environment with:

.\.venv\Scripts\Activate.ps1

Create a first diagnostic package:

doctor-link report . --out DoctorReports
PACKAGE_DIR=$(find DoctorReports -mindepth 1 -maxdepth 1 -type d | head -n 1)
doctor-link collect "$PACKAGE_DIR" --project-root . --command "python --version"
doctor-link verify "$PACKAGE_DIR" --write-back
doctor-link view "$PACKAGE_DIR" --build-only

See Quick Start and Installation for Windows alternatives and complete validation instructions.

Automatically solve a reproducible Python or Node.js-project problem:

# Preview only: reproduces the issue and writes the repair plan.
doctor-link solve /path/to/project \
  --problem "Checkout creates two charges" \
  --test-command "python -m pytest tests/test_checkout.py -q"

# Explicitly authorize branch creation and Codex edits.
doctor-link solve /path/to/project \
  --problem "Checkout creates two charges" \
  --test-command "python -m pytest tests/test_checkout.py -q" \
  --allow-repair

For a Node.js project with a non-placeholder scripts.test, Doctor link automatically selects npm test, pnpm test, yarn test, or bun run test from packageManager and lockfile evidence. If no test script exists but JavaScript test files are present, it falls back to node --test:

doctor-link solve /path/to/node-project \
  --problem "Concurrent updates lose the latest value" \
  --test-command "npm test" \
  --allow-repair

See Automatic Solve with Codex for command discovery, status codes, evidence files, and rollback.

For an npm, Yarn, or pnpm workspace, keep the repository root and select a package with --package packages/name. Interrupted repair receipts can continue with doctor-link solve --resume SESSION_DIR --allow-repair. Repeatable multi-project suites use doctor-link benchmark benchmark.yml --out DoctorReports/benchmark and report reproduction and repair-success metrics.

Typical diagnostic workflow

preflight → report → collect → assert → reproduce/test → verify → handoff/view

For the automatic Python or Node.js path, the complete workflow is:

solve preview → explicit approval → repair branch → Codex round → protected-input check → independent verification → verified/blocked/failed

1. preflight checks readiness without running repository commands.
2. report creates the diagnostic package.
3. collect adds reviewed evidence and command output.
4. assert records human-confirmed behavior.
5. reproduce and test execute explicitly configured checks without a shell.
6. verify identifies missing evidence and determines closure status.
7. handoff or view prepares AI context or a local review interface.

Failed reproductions, failed required test jobs, and incomplete verification return a non-zero exit code even when --json is used. See Automated diagnosis reliability for the complete evidence and status rules.

Safety model

• Doctor link is local-first and does not upload diagnostic packages by default.
• Reproduction and test-matrix commands do not invoke a shell; pipelines, redirection, command substitution, and unsafe operators are rejected.
• Adapter and plugin execution is dry-run by default and requires explicit --allow-run approval.
• Automatic code repair requires --allow-repair, a clean Git working tree, and a failing executable check. Codex remains sandboxed to workspace-write; Doctor link does not auto-commit or push.
• Automatic repair hash-protects tests, package manifests and lockfiles, test configuration, reproduction/test catalogs, and directly referenced verification scripts. Protected-input changes block verified; the explicit exception --allow-verification-changes returns review_required instead of success.
• --allow-repair invokes the authenticated Codex service and may send the bounded prompt, failing output, and inspected repository context. Review the preview and remove sensitive data before authorization.
• Generated packages may still contain project-sensitive evidence. Review privacy and redaction reports before sharing them.
• Do not attach secrets or private diagnostic packages to public GitHub issues.

Read SECURITY.md, sensitive data handling, and the export security checklist.

Development validation

python -m pip install -e '.[dev]'
ruff check doctor_link tests scripts
pytest -q --cov=doctor_link --cov-branch --cov-fail-under=85
bandit -r doctor_link -ll
pip-audit
python -m build
python scripts/validate_distribution_contents.py dist
python -m twine check dist/*
bash scripts/e2e_validate.sh "$(pwd)"
bash scripts/p7_runtime_validate.sh "$(pwd)"

GitHub Actions runs the full Python matrix, security checks, package installation, and cross-platform smoke checks for pull requests targeting main.

Repository map

Path	Purpose
doctor_link/	Python package and CLI runtime.
.doctorlink/	Repository-owned diagnostic strategies, catalogs, and configuration.
tests/	Unit, integration, regression, packaging, security, and documentation tests.
scripts/	E2E, self-validation, package-content, and release helper scripts.
schemas/	Versioned diagnostic package schemas.
examples/	Example projects, configurations, handoff data, and diagnostic packages.
docs/	User guides, architecture, validation evidence, release policy, and historical audits.
.github/	Issue template, PR template, Dependabot, CI, manual validation, self-validation, and release workflows.

Documentation map

• Quick Start
• Installation
• CLI reference
• Automated diagnosis reliability
• Automatic Solve with Codex
• Full capability validation
• Platform integration roadmap: English | 中文
• Product overview
• Architecture overview
• GitHub repository and workflow guide
• Contributing
• Security policy
• Project status
• Validation certification
• Release policy

Project boundaries

Doctor link currently does not provide a hosted web platform, cloud synchronization, an external account system, telemetry, a marketplace, production key management, hosted enterprise archives, hosted diagnostic knowledge bases, or production RBAC. Those capabilities must not be inferred from planning documents.

License

Doctor link is licensed under the MIT License.