docs: rebuild Doctor structured repair RFC 0004

[giodl73-repo]

What Problem This Solves

The accepted Doctor health RFC remained under rfcs/needs_refactoring/ and still described the migration as future work, before the tracked 44-of-44 lint coverage milestone and the addition of doctor --lint --all.

Why This Change Was Made

Moves the Doctor RFC to numbered RFC 0004, rebuilds it in the current repository template, and adds a normative sidecar specification. The update documents ordered core contributions, default versus complete lint selection, --all / --only / --skip, structured repair results, post-repair validation, the plugin SDK boundary, and the completed legacy rule-family lint migration.

The RFC intentionally leaves general repair dry-run as a future project. Existing dryRun / diff / effect plumbing is documented as substrate, not as a completed CLI or parity claim.

User Impact

RFC readers and implementers now have a current Doctor structured-health and repair contract in the normal RFC layout. The stale needs_refactoring copy is removed.

Evidence

• Audited current openclaw/openclaw Doctor lint selection, CLI documentation, health contribution ordering, structured repair types, and representative migrated checks.
• Cross-checked the 44-of-44 tracked migration milestone against the Doctor project record while distinguishing it from the growing live registry size.
• git diff --check

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 21, 2026, 12:22 PM ET / 16:22 UTC.

ClawSweeper review

What this changes

The PR replaces the archived Doctor health RFC with numbered RFC 0004 and a sidecar specification for structured linting and repair behavior.

Merge readiness

⚠️ Ready for maintainer review - 4 items remain

Keep this PR open: RFC 0004 is marked accepted while its required implementation-issue field is blank, so it does not meet the repository’s RFC lifecycle before merge.

Priority: P3
Reviewed head: 6a2a0c2bc163d600cd1ef52d57c8f10993f06251
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The RFC replacement is coherent, but its unresolved lifecycle metadata prevents acceptance.
Proof confidence	🌊 off-meta tidepool	Not applicable: All changed files are RFC documentation, so runtime behavior proof is not required.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: All changed files are RFC documentation, so runtime behavior proof is not required.
Evidence reviewed	5 items	RFC lifecycle requirement: The repository requires a new RFC to begin as draft; once accepted, it must have a GitHub implementation issue URL before merge. Lifecycle metadata mismatch: The new RFC sets status to accepted but leaves issue empty. Review continuity: The RFC file is unchanged since the prior reviewed head, so the prior lifecycle finding remains unresolved rather than being a newly discovered concern.
Findings	1 actionable finding	[P2] Record the implementation issue before accepting RFC 0004
Security	None	None.

How this fits together

This RFC repository records design contracts for OpenClaw Doctor, whose health checks produce findings and may perform repairs. RFC lifecycle metadata connects an accepted contract to its implementation issue so implementers can trace the approved work.

flowchart LR
A[Doctor behavior] --> B[Structured health contract]
B --> C[RFC 0004]
C --> D[RFC lifecycle metadata]
D --> E[Implementation issue]
E --> F[Implementation work]

Loading

Decision needed

Question	Recommendation
Should RFC 0004 be accepted now with a linked implementation issue, or remain a draft proposal?	Keep RFC 0004 draft: Change the metadata to draft until a maintainer accepts the contract and records its implementation issue.

Why: Acceptance makes the Doctor contract normative, but the required implementation handoff is absent and cannot be inferred from this documentation-only branch.

Before merge

• Add real behavior proof - Not applicable: All changed files are RFC documentation, so runtime behavior proof is not required.
• Record the implementation issue before accepting RFC 0004 (P2) - The repository lifecycle requires an accepted RFC to name its implementation issue, but this new RFC leaves issue blank. Keep the RFC draft until acceptance, or add the canonical issue URL before merge so readers can trace the approved contract to its implementation.
• Resolve merge risk (P1) - Merging an accepted RFC without an implementation issue would present an untracked Doctor contract as approved and remove the required handoff to implementation work.

Findings

• [P2] Record the implementation issue before accepting RFC 0004 — rfcs/0004-doctor-structured-health-and-repair.md:7-8

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC replacement scope	2 added, 1 removed; 406 additions, 224 deletions	The PR replaces the archived RFC with a numbered RFC and normative sidecar, making lifecycle metadata especially important.

Merge-risk options

Maintainer options:

1. Restore the RFC lifecycle state (recommended)
   Keep the RFC draft unless a maintainer-approved implementation issue URL is added before merge.

Technical review

Best possible solution:

Merge a lifecycle-valid RFC: keep it draft until acceptance, or record the approved implementation issue URL before retaining accepted status.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a runtime reproduction: source inspection directly shows accepted status alongside a blank implementation-issue field, contrary to the checked-in lifecycle policy.

Is this the best way to solve the issue?

No: the current accepted metadata is not the maintainable path because it omits the required implementation handoff; keep the RFC draft or link the approved issue.

Full review comments:

• [P2] Record the implementation issue before accepting RFC 0004 — rfcs/0004-doctor-structured-health-and-repair.md:7-8
  The repository lifecycle requires an accepted RFC to name its implementation issue, but this new RFC leaves issue blank. Keep the RFC draft until acceptance, or add the canonical issue URL before merge so readers can trace the approved contract to its implementation.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.99

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against af708f0ddb6f.

Labels

Label justifications:

• P3: This is low-urgency RFC documentation governance rather than an executable user-facing regression.
• merge-risk: 🚨 other: The accepted-but-unlinked metadata can create an unsupported normative contract without a tracked implementation handoff.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: All changed files are RFC documentation, so runtime behavior proof is not required.

Evidence

What I checked:

• RFC lifecycle requirement: The repository requires a new RFC to begin as draft; once accepted, it must have a GitHub implementation issue URL before merge. (README.md:88, 6a2a0c2bc163)
• Lifecycle metadata mismatch: The new RFC sets status to accepted but leaves issue empty. (rfcs/0004-doctor-structured-health-and-repair.md:7, 6a2a0c2bc163)
• Review continuity: The RFC file is unchanged since the prior reviewed head, so the prior lifecycle finding remains unresolved rather than being a newly discovered concern. (rfcs/0004-doctor-structured-health-and-repair.md:7, 6a2a0c2bc163)
• Current-main comparison: Current main still contains the archived Doctor RFC and does not contain the proposed numbered RFC or sidecar, so this PR is not already implemented on main. (rfcs/needs_refactoring/doctor-health-upgrades.md:1, af708f0ddb6f)
• RFC-process provenance: The current RFC-process guidance appears to date to the merged RFC guidance refresh authored by kevinlin-openai. (README.md:78, e366ea9825a4)

Likely related people:

• kevinlin-openai: Authored the RFC-process update that is the likely provenance for the lifecycle guidance governing this PR. (role: RFC lifecycle guidance author; confidence: medium; commits: e366ea9825a4; files: README.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Set the RFC to draft or add the maintainer-approved implementation issue URL before requesting merge.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (42 earlier review cycles; latest 8 shown)

• reviewed 2026-08-09T14:50:54.304Z sha 6a2a0c2 :: needs real behavior proof before merge. :: [P2] Record the implementation issue before marking the RFC accepted
• reviewed 2026-08-09T19:49:24.942Z sha 6a2a0c2 :: needs real behavior proof before merge. :: [P2] Link the implementation issue before accepting RFC 0004
• reviewed 2026-08-09T22:01:07.727Z sha 6a2a0c2 :: needs real behavior proof before merge. :: [P2] Link the implementation issue before accepting RFC 0004
• reviewed 2026-08-09T23:09:52.048Z sha 6a2a0c2 :: needs real behavior proof before merge. :: [P2] Record the implementation issue before accepting RFC 0004
• reviewed 2026-08-11T03:13:35.748Z sha 6a2a0c2 :: needs real behavior proof before merge. :: [P2] Link the accepted RFC to its implementation issue
• reviewed 2026-08-13T19:29:21.803Z sha 6a2a0c2 :: needs real behavior proof before merge. :: [P2] Link the accepted RFC to its implementation issue
• reviewed 2026-08-13T20:35:37.722Z sha 6a2a0c2 :: needs real behavior proof before merge. :: [P2] Record the implementation issue before accepting RFC 0004
• reviewed 2026-08-15T09:10:49.589Z sha 6a2a0c2 :: needs real behavior proof before merge. :: [P2] Link the implementation issue before marking RFC 0004 accepted

[steipete]

Closing as shipped — the behavior this rebuild documents is live in the product.

Doctor structured health checks shipped and are canonical in the product: openclaw doctor --lint with --all, --only <id>, and --severity-min <level> is live on current main (d7c57716841), covering the registered check catalog this rebuild describes, documented at https://docs.openclaw.ai/cli/doctor. The originally accepted RFC remains under needs_refactoring/ as the historical decision record.

Same basis as #40: we're not restructuring accepted RFCs for surfaces that have since shipped — product docs and code are canonical for shipped behavior, and the RFC repo keeps decision records as accepted. This close reflects that policy, not the rebuild's accuracy.

What would reopen this: a new Doctor capability decision (new check families, changed repair ownership) proposed as a fresh RFC.