Sw Doctor

---
name: sw-doctor
description: >-
  Specwright health check. Validates shared config, anchor docs, workflow and
  session state, commands, gates, and hooks. May backfill shipped PR metadata
  when it can prove the mapping safely.
argument-hint: ""
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
---

# Specwright Doctor

## Goal

Validate that a Specwright installation is coherent across the tracked
project-artifact root, shared repo-state root, and per-worktree session model,
then print actionable repair hints using the same runtime-root and ownership
vocabulary the adapters expose.

## Inputs

- `{projectArtifactsRoot}/config.json`
- `{projectArtifactsRoot}/CONSTITUTION.md` and `{projectArtifactsRoot}/CHARTER.md`
- `{worktreeStateRoot}/session.json` when present
- `{repoStateRoot}/work/*/workflow.json`
- `{workArtifactsRoot}/{workId}/approvals.md` and `{workDir}/review-packet.md`
  when present
- gate skill files, hook config, and configured commands

## Outputs

- PASS/WARN/FAIL health table
- Optional backfill of `prNumber` and `prMergedAt` on the owning work's
  `workflow.json`

## Constraints

**Pre-condition (LOW freedom):**
- If neither the shared layout nor the legacy fallback can be resolved, stop
  immediately and tell the user to run `/sw-init`.
- Always report layout status first: `shared/session`, `legacy fallback`, or
  `missing`.
- When layout resolves, describe the active runtime mode explicitly:
  `project-visible` runtime roots under `.specwright-local/` are the preferred
  interactive default; `git-admin` roots under `.git/specwright/` are
  compatibility mode.

**Checks (LOW freedom — run all 13 in order):**
1. **Anchor docs** — tracked Constitution and Charter exist and are non-empty
2. **Config** — tracked config parses and contains `gates` and `git`
3. **State** — current session parses when present, every discovered workflow
   parses with a null or fresh per-work lock, and layout status is explicit
4. **Gates** — enabled gate skills exist
5. **Build command** — configured build command exists on PATH
6. **Test command** — configured test command exists on PATH
7. **Format/lint** — configured format or lint commands exist on PATH
8. **Hooks** — hook manifest parses and referenced hook files exist
9. **Backlog config** — configured backlog target is usable
10. **ast-grep** — INFO availability only
11. **OpenGrep** — INFO availability only
12. **LSP** — PASS/WARN/INFO based on available platform or standalone LSP
13. **STATE_DRIFT** — enumerate repo-wide workflows and flag shipped units with
    `status=shipped` and `prNumber=null`

Within the State pass, check all of the following and report them by name:
- layout status for the current checkout
- resolved `projectArtifactsRoot`, `workArtifactsRoot`, and the authoritative
  runtime roots (`repoStateRoot` and `worktreeStateRoot`) for the current
  checkout
- session attachment consistency between `session.json` and the owning
  `workflow.json`
- dead sessions where a recorded attachment points at a missing or removed
  worktree
- legacy-write drift where the shared layout exists but checkout-local legacy
  state files are still being treated as writable sources
- approval freshness for the selected unit when approvals exist
- review-packet presence for the selected unit when verify or ship artifacts
  should exist
- live ownership conflicts that should route the operator to `/sw-adopt`
  instead of implying generic takeover

State-pass output must report the authoritative runtime roots clearly so the
user can see which `repoStateRoot` and `worktreeStateRoot` are in force.

Within the Config pass, check all of the following and report them by name:
- queue validation without the required provider-aware configuration surface
- Claude-oriented installs that remain on `git-admin` even though
  `project-visible` runtime roots are the recommended default for that setup
- work-artifact publication mode that points at clone-local runtime roots,
  session state, or symlinked `.git` mirrors instead of an explicit tracked
  artifact path
- `config.git.runtime.projectVisibleRoot` values that point at tracked project
  artifacts or `.git`-mirrored paths instead of a dedicated project-visible
  runtime root

Reject project-visible roots that overlap tracked project artifacts or `.git`-mirrored paths, and name `config.git.runtime.projectVisibleRoot` in the result.

CONFIG_MISMATCH findings must name the offending config key and print the
corrective action.

STATE_DRIFT findings must print the inline remediation command
`sw-status --repair {unitId}` and include the owning work ID.

**STATE_DRIFT backfill (MEDIUM freedom):**
- On the first invocation, attempt a one-time backfill for any shipped unit with
  `status=shipped` and `prNumber=null`.
- Candidate set: shipped units with `prNumber=null` across all discovered
  workflows.
- Detection order is strict: `gh` lookup, then `git log` / merge confirmation,
  then warn and leave the fields untouched.
- Backfill order is `gh`, then `git log`, then warn.
- Backfill scope is limited to `prNumber` and `prMergedAt` on the owning work's
  workflow file.
- Backfill never modifies `status`; it only writes `prNumber` and `prMergedAt`.

**Output format (MEDIUM freedom):**
- Print the same PASS/WARN/FAIL/INFO table shape as the existing doctor output.
- STATE_DRIFT findings must include the owning work ID and unit ID so the user
  can distinguish repo-wide issues.

**Workflow mutation scope (LOW freedom):**
- The only allowed mutation is STATE_DRIFT backfill.
- When mutating a work's `workflow.json`, follow `protocols/state.md`.
- Doctor never modifies `status`; only `prNumber` and `prMergedAt` may change.
- It is not a core workflow stage and never claims top-level work ownership.
- Any repair guidance beyond PR backfill must remain bounded to the documented
  migration surface: tracked docs/config under `{projectArtifactsRoot}`, split
  per-work workflows under `{repoStateRoot}`, and this worktree's
  `{worktreeStateRoot}/session.json`.

## Protocol References

- `protocols/context.md` -- logical-root loading
- `protocols/state.md` -- per-work workflow format and lock handling

## Failure Modes

| Condition | Action |
|---|---|
| shared config missing | fail that check and continue |
| workflow parse error | fail the state check and identify the owning work |
| all checks pass | print the table and say all checks passed |
| hooks absent | INFO: no hooks configured |