dovetail

dovetail

Checks whether a repository agrees with itself, and walks through what it finds.

Two layers produce findings. Exact findings are computed in Python - links, anchors, orphans, duplicates, flag and signature drift, conventions, git-history signals. They are certain. Judged findings come from reviewers - contradictions, semantic staleness, spec drift, non-Python dead code. They are probabilistic.

The user must always know which they are looking at. Never blur the two.

Run

1. Scan (always)

python3 ${CLAUDE_SKILL_DIR}/scripts/scan.py <repo-path> --format json

Seconds, no network, no model. Never modifies the target.

Read the JSON: findings, suppressed, counts, failed_checks, profile, file_count, edge_count.

If it exits 2, report the error and stop - the repository is not a git checkout, or .dovetail/config.toml is invalid. Do not proceed on defaults; a config the user wrote is one they expect to take effect.

2. Dispatch the judgement reviewers (unless the user said "quick" or "exact only")

Start these before triaging, so they land while the user works through the certain findings. Layer 1 finishes before the first reviewer returns, and a run abandoned after two minutes has still delivered every broken link and duplicate in the repository.

Get the clusters the contradiction reviewer needs:

python3 -c "import sys; sys.path.insert(0, '${CLAUDE_SKILL_DIR}/scripts'); \
from discover import discover; from refgraph import build_graph; from claimscan import build_clusters; \
import json; inv=discover('<repo-path>'); print(json.dumps(build_clusters(inv, build_graph('<repo-path>', inv))))"

Then spawn one subagent per reviewer, in parallel. For each:

• Read its rubric from ${CLAUDE_SKILL_DIR}/references/reviewers/<name>.md
• Read the contract from ${CLAUDE_SKILL_DIR}/references/finding-schema.md
• Give it its context: clusters for contradiction, docs for staleness / spec-flow / xref / convention, code for code-hygiene
• Pass the model override explicitly. Never let a reviewer inherit the orchestrator's model.