Expose heartbeat template doctor lint findings by giodl73-repo · Pull Request #98400 · openclaw/openclaw

giodl73-repo · 2026-07-01T04:21:44Z

Summary

add a default-disabled core/doctor/heartbeat-template structured health check for legacy HEARTBEAT.md documentation-template wrappers
reuse the existing heartbeat template analyzer so lint and legacy Doctor repair classify the same file shapes
keep actual replacement in the existing legacy doctor --fix path; this PR is lint-only and does not add a structured repair/dry-run hook
no config, plugin, SDK, persisted data, or repair-path contract changes

Public surface

Default doctor --lint is unchanged.
The check runs only with --only core/doctor/heartbeat-template or --all.

Real behavior proof

Source CLI with isolated OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, and workspace containing a legacy fenced HEARTBEAT.md template:
- doctor --lint --json ran broad default lint with heartbeat=0, proving default lint skips the new default-disabled check.
- doctor --lint --json --only core/doctor/heartbeat-template ran one selected check, emitted one core/doctor/heartbeat-template warning with requirement: "legacy-template", and exited 1.

Validation after Omar fix

node scripts/run-vitest.mjs src/commands/doctor-heartbeat-template-repair.test.ts src/flows/doctor-health-contributions.test.ts (73 tests)
changed-file pnpm exec oxfmt --check
changed-file pnpm exec oxlint
node scripts/plugin-sdk-surface-report.mjs --check
git diff --check

giodl73-repo · 2026-07-01T04:22:07Z

@clawsweeper review

clawsweeper · 2026-07-01T04:22:09Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

clawsweeper · 2026-07-01T04:29:36Z

Codex review: needs maintainer review before merge. Reviewed July 2, 2026, 7:42 PM ET / 23:42 UTC.

Summary
The PR adds a default-disabled core/doctor/heartbeat-template Doctor lint check that maps existing legacy HEARTBEAT.md template analysis into structured findings and focused tests.

PR surface: Source +74, Tests +120. Total +194 across 4 files.

Reproducibility: not applicable. this is an additive Doctor lint surface rather than a bug report. The PR body and focused tests cover both the default skip path and explicit --only core/doctor/heartbeat-template warning path.

Review metrics: 1 noteworthy metric.

Doctor lint surface: 1 opt-in core check added. The stable check id is user-facing Doctor lint surface, while defaultEnabled: false keeps broad default lint behavior unchanged.

Stored data model
Persistent data-model change detected: migration/backfill/repair: src/commands/doctor-heartbeat-template-repair.test.ts, migration/backfill/repair: src/commands/doctor-heartbeat-template-repair.ts, migration/backfill/repair: src/flows/doctor-health-contributions.test.ts, migration/backfill/repair: src/flows/doctor-health-contributions.ts, unknown-data-model-change: src/commands/doctor-heartbeat-template-repair.test.ts, unknown-data-model-change: src/commands/doctor-heartbeat-template-repair.ts, and 1 more. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

none.

Risk before merge

[P1] The protected maintainer label means this PR should stay on a human maintainer review path even though no code defect was found.

Maintainer options:

Decide the mitigation before merge
Land the lint-only opt-in check after maintainer review and exact-head checks, preserving the existing legacy doctor --fix path as the only repair owner.
Pause or close
Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

[P2] The protected maintainer label keeps this PR on the human maintainer path, and there is no narrow patch defect for ClawSweeper to repair.

Security
Cleared: Cleared: the diff touches local Doctor lint helper code and tests only, with no dependency, workflow, package, permission, secret, or download-path changes.

Review details

Best possible solution:

Land the lint-only opt-in check after maintainer review and exact-head checks, preserving the existing legacy doctor --fix path as the only repair owner.

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

Not applicable: this is an additive Doctor lint surface rather than a bug report. The PR body and focused tests cover both the default skip path and explicit --only core/doctor/heartbeat-template warning path.

Is this the best way to solve the issue?

Yes: reusing the existing heartbeat-template analyzer behind a default-disabled structured health check is the narrowest maintainable solution. The latest head keeps real mutation in the existing legacy doctor --fix contribution, avoiding the unreachable repair-preview path flagged in review.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

P3: This is a low-risk additive Doctor lint ergonomics change with focused coverage and no default behavior change.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): Sufficient: the PR body includes after-change source CLI proof for default lint skip and explicit heartbeat-template warning behavior, plus focused validation commands.
proof: sufficient: Contributor real behavior proof is sufficient. Sufficient: the PR body includes after-change source CLI proof for default lint skip and explicit heartbeat-template warning behavior, plus focused validation commands.

Evidence reviewed

PR surface:

Source +74, Tests +120. Total +194 across 4 files.

View PR surface stats

Area	Files	Added	Net
Source	2	74	+74
Tests	2	120	+120
Docs	0	0	0
Config	0	0	0
Generated	0	0	0
Other	0	0	0
Total	4	194	+194

What I checked:

Repository policy read: Root AGENTS.md was read fully; its read-beyond-diff, protected-label, proof, and Doctor review guidance affected this review. (AGENTS.md:1, d47308f8008c)
Current main lacks this lint exposure: On current main, the heartbeat contribution still only keeps the legacy runHeartbeatTemplateRepairHealth runner and has no structured healthChecks entry for core/doctor/heartbeat-template. (src/flows/doctor-health-contributions.ts:1839, d47308f8008c)
Latest release lacks this lint exposure: Release v2026.6.11 also has the legacy heartbeat repair contribution without the structured heartbeat-template lint check. (src/flows/doctor-health-contributions.ts:1428, e085fa1a3ffd)
PR registers an opt-in core lint check: At the PR head, the heartbeat contribution adds core/doctor/heartbeat-template with defaultEnabled: false and a detect hook while preserving the legacy repair runner. (src/flows/doctor-health-contributions.ts:1842, f76623016cac)
PR reuses existing classification: The new collector reads the workspace heartbeat file, calls the existing analyzer, returns no finding for clean or missing files, and maps repairable/custom-content cases into warnings. (src/commands/doctor-heartbeat-template-repair.ts:157, f76623016cac)
Lint selection path supports the new shape: runDoctorLintChecks skips default-disabled checks unless --all or explicit --only selection includes them, which matches this PR's public-surface claim. (src/flows/doctor-lint-flow.ts:38, d47308f8008c)

Likely related people:

hxy91819: Merged PR fix(agents): separate heartbeat runtime template #85416 added doctor-heartbeat-template-repair.ts, its tests, and the heartbeat Doctor contribution this PR extends. (role: introduced current heartbeat repair behavior; confidence: high; commits: 75221e0550ec; files: src/commands/doctor-heartbeat-template-repair.ts, src/commands/doctor-heartbeat-template-repair.test.ts, src/flows/doctor-health-contributions.ts)
giodl73-repo: Merged PRs Keep core doctor health in contribution order #86627 and Doctor: expose workspace status findings #97358 established the ordered core Doctor health-check path and adjacent default-disabled lint exposure pattern. (role: recent Doctor lint/contribution area contributor; confidence: high; commits: e56fd1dc0466, 4ac5cf863673; files: src/flows/doctor-health-contributions.ts, src/flows/doctor-health-contributions.test.ts, src/commands/doctor-lint.ts)
omarshahine: Their review comment identified the unreachable structured repair-preview path, and the latest head changed to the lint-only shape in response. (role: recent reviewer; confidence: medium; files: src/flows/doctor-health-contributions.ts, src/commands/doctor-heartbeat-template-repair.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

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.

giodl73-repo · 2026-07-02T00:30:16Z

@clawsweeper re-review

Added dry-run repair effects to the current heartbeat-template PR instead of deferring them to a later follow-up. Pure legacy HEARTBEAT.md templates now preview a file replacement effect/diff; custom-content findings remain manual/skipped.

Head: 2e9f208071911fbd928474c6fca46a83a7658478

Validation: changed-file oxfmt/oxlint, focused heartbeat/contribution Vitest 73 tests, core tsgo, core-test tsgo, and git diff check.

clawsweeper · 2026-07-02T00:30:19Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

giodl73-repo · 2026-07-02T17:25:53Z

@clawsweeper review

clawsweeper · 2026-07-02T17:26:12Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

omarshahine · 2026-07-02T22:36:44Z

Codex review finding:

The structured repair preview added here is not reachable from any supported openclaw doctor path. createDoctorHealthContribution only uses runStructuredDoctorHealthContribution when no explicit run is supplied (src/flows/doctor-health-contributions.ts:144-151), but this contribution keeps run: runHeartbeatTemplateRepairHealth (src/flows/doctor-health-contributions.ts:1840-1862). That legacy runner calls maybeRepairHeartbeatTemplate, so the new repairHeartbeatTemplateHealthFindings() path is only exercised by focused tests, not by openclaw doctor --fix or normal Doctor execution. The generic structured repair pass also filters to extension checks (src/flows/doctor-health-contributions.ts:440-453, src/flows/health-check-registry.ts:29-40), and the CLI exposes --only only for --lint (src/cli/program/register.maintenance.ts:42-83), so there is no selected doctor fix --dry-run --only core/doctor/heartbeat-template surface to hit this hook.

Best fix: either wire this core check into the actual repair flow, for example via the default structured runner or an explicit runCoreContributionHealthRepair call, or keep the PR lint-only and remove the unreachable repair hook/tests/body claim.

giodl73-repo · 2026-07-02T22:55:46Z

Addressed Omar's reachability finding by making this PR lint-only again.

What changed:

Removed the structured repair() hook from core/doctor/heartbeat-template because core structured repair selection is not currently reachable from the supported Doctor CLI.
Removed the unreachable dry-run helper/tests and kept the existing legacy runHeartbeatTemplateRepairHealth / maybeRepairHeartbeatTemplate path as the real doctor --fix owner.
The PR now only exposes default-disabled lint findings for heartbeat template readiness.

Validation:

node scripts/run-vitest.mjs src/commands/doctor-heartbeat-template-repair.test.ts src/flows/doctor-health-contributions.test.ts (73 tests)
changed-file oxfmt --check
changed-file oxlint
node scripts/plugin-sdk-surface-report.mjs --check
git diff --check

@clawsweeper review

clawsweeper · 2026-07-02T22:55:49Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

giodl73-repo · 2026-07-02T23:31:03Z

@clawsweeper review final lint-only wording/body synced after Omar fix

giodl73-repo · 2026-07-03T00:40:41Z

Merged #98400 by head-pinned squash.

PR head: f76623016cace286895c53f6641cfab24603b5c6
Merge commit: dce1b0a87afb64cbc54b750f5dc2fb2ce6b34bbe
Scope: default-disabled core/doctor/heartbeat-template lint findings only; real replacement remains in legacy doctor --fix.

Validation before merge:

Hosted PR checks green.
node scripts/run-vitest.mjs src/commands/doctor-heartbeat-template-repair.test.ts src/flows/doctor-health-contributions.test.ts (73 passed)
changed-file pnpm exec oxfmt --check
changed-file pnpm exec oxlint
node scripts/plugin-sdk-surface-report.mjs --check
git diff --check

Maintainer wrapper note: WSL is currently failing to start on this machine (0x80072745), and Git Bash lacks wrapper dependencies (jq rg node gh), so I used the branch-protection-compatible head-pinned squash path after scoped local proof and green hosted checks.

Expose default-disabled Doctor lint findings for legacy HEARTBEAT.md documentation-template wrappers. - Reuses the existing heartbeat template analyzer for structured `HealthFinding` output. - Keeps replacement/mutation in the existing legacy `doctor --fix` path; no structured dry-run repair hook in this PR. - Default `doctor --lint` remains unchanged; explicit `--only core/doctor/heartbeat-template` and `--all` can select it. Validation: - Hosted PR checks green on head f766230. - `node scripts/run-vitest.mjs src/commands/doctor-heartbeat-template-repair.test.ts src/flows/doctor-health-contributions.test.ts` (73 passed) - changed-file `pnpm exec oxfmt --check` - changed-file `pnpm exec oxlint` - `node scripts/plugin-sdk-surface-report.mjs --check` - `git diff --check`

openclaw-barnacle Bot added commands Command implementations size: S maintainer Maintainer-authored PR labels Jul 1, 2026

giodl73-repo marked this pull request as ready for review July 1, 2026 16:33

giodl73-repo force-pushed the doctor-heartbeat-template-lint-findings branch from 13df304 to 2e9f208 Compare July 2, 2026 00:30

openclaw-barnacle Bot added size: M and removed size: S labels Jul 2, 2026

clawsweeper Bot added status: 🔁 re-review loop A fresh ClawSweeper review was explicitly requested after the latest review. and removed status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels Jul 2, 2026

giodl73-repo added 2 commits July 2, 2026 10:18

Expose heartbeat template doctor lint findings

09e645d

doctor: preview heartbeat template repairs

8e49026

giodl73-repo force-pushed the doctor-heartbeat-template-lint-findings branch from 2e9f208 to 8e49026 Compare July 2, 2026 17:25

clawsweeper Bot added status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed status: 🔁 re-review loop A fresh ClawSweeper review was explicitly requested after the latest review. labels Jul 2, 2026

Keep heartbeat template doctor check lint-only

f766230

openclaw-barnacle Bot removed the size: M label Jul 2, 2026

openclaw-barnacle Bot added the size: S label Jul 2, 2026

giodl73-repo merged commit dce1b0a into openclaw:main Jul 3, 2026
109 of 111 checks passed

giodl73-repo mentioned this pull request Jul 3, 2026

Expose legacy plugin manifest doctor lint findings #98695

Merged

github-actions Bot mentioned this pull request Jul 3, 2026

📡 Upstream Digest — 2026-07-03 02:07 UTC curtismercier/openclaw-mods#1194

Open

Uh oh!

Uh oh!

Conversation

giodl73-repo commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Public surface

Real behavior proof

Validation after Omar fix

Uh oh!

giodl73-repo commented Jul 1, 2026

Uh oh!

clawsweeper Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clawsweeper Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giodl73-repo commented Jul 2, 2026

Uh oh!

clawsweeper Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giodl73-repo commented Jul 2, 2026

Uh oh!

clawsweeper Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

omarshahine commented Jul 2, 2026

Uh oh!

giodl73-repo commented Jul 2, 2026

Uh oh!

clawsweeper Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

giodl73-repo commented Jul 2, 2026

Uh oh!

Uh oh!

giodl73-repo commented Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

giodl73-repo commented Jul 1, 2026 •

edited

Loading

clawsweeper Bot commented Jul 1, 2026 •

edited

Loading

clawsweeper Bot commented Jul 1, 2026 •

edited

Loading

clawsweeper Bot commented Jul 2, 2026 •

edited

Loading

clawsweeper Bot commented Jul 2, 2026 •

edited

Loading

clawsweeper Bot commented Jul 2, 2026 •

edited

Loading