doctor

Report what is present, what is missing, and what degrades as a result. Never report a capability as available without checking it.

pdkit doctor                  # required tools, config layers, $PDKIT_HOME, hooks, MCP
pdkit doctor --gate-selftest  # plus: drive the real hooks the manifest registers
pdkit doctor --repo <path>    # act on a repository other than the current one

Reading the report

Three levels — required, optional, later — and four results. The distinction that matters is between the last two:

A warning is not a failure and must not be reported as one. A doctor that exits non-zero on every optional gap stops being run, and a check nobody runs is worse than no check.

The self-test

--gate-selftest is not part of the routine run: it spawns the hook once per probe and takes a few seconds. Run it after installing, after upgrading, and after touching anything under lib/hooks/.

It is the only check that answers "is the protection actually on". Every unit test in the suite stays green while a plugin with a broken manifest gates nothing at all, so this one drives real commands through the binary the manifest names: seventeen for the push gate, two for the ownership hook.

If it reports a miss, nothing else in the report matters until it is fixed.

Warnings that are decisions rather than breakage

Do not offer to "fix" these — say what they mean and let the user decide:

• package-map:layers — packages/api, packages/webview-api and storybook belong to no layer. That decides merge order for slices, and the decision belongs to stage 3.
• config:gates — a key the plugin stopped reading is still in a personal config, where it looks like a setting somebody chose. The detail names the key and the version that retired it.
• mcp:playwright — three outcomes, not two. Absent means /pd:validate produces a checklist instead of a run and never sets PASS. Present without --cdp-endpoint, or aimed at a port other than validation.app.debug_port, is a warning: the server is healthy and looking at a browser of its own, which reads as working until a validation run finds nothing there. The detail carries the command to fix it, -s user included — local scope is keyed by directory and no worktree would see it.
• validate:app — a different problem with a different fix. The server can be configured perfectly and validation still have nothing to drive, because the working tree was never built.
• config:arrays — a list in your config.yaml has fallen behind the shipped default. Lists replace rather than merge, so one copied by init and never edited stays at the value shipped that day; delete the key to follow the default again, or extend it deliberately.

When something is red

Read the detail line: every failure here is written to say what to do, not just what is wrong. home failing means pdkit init has not run. config:merge failing names the file and the line. gh-auth failing means gh auth login.

Report the findings to the user rather than repairing the environment. The one exception is a stale package map, where pdkit init is the whole fix and is safe to offer.