Skip to content

docs: align source contract wording#100186

Merged
steipete merged 1 commit into
mainfrom
codex/align-doc-contract-wording
Jul 5, 2026
Merged

docs: align source contract wording#100186
steipete merged 1 commit into
mainfrom
codex/align-doc-contract-wording

Conversation

@steipete

@steipete steipete commented Jul 5, 2026

Copy link
Copy Markdown
Contributor

What Problem This Solves

#100182 and #100183 landed concurrently with different exact wording for three documentation guards. The combined main state fails the environment, Talk-default, and cron-fallback contract suites.

Why This Change Was Made

Use the canonical wording selected by #100183 while preserving the behavior and broader documentation restored by #100182. This is a three-line docs-only reconciliation; no test expectations are changed.

User Impact

No runtime change. The docs remain accurate, and main returns to a self-consistent source/contract state.

Evidence

  • node scripts/run-vitest.mjs run src/docs/environment-docs.test.ts src/config/talk-defaults.test.ts src/cron/isolated-agent/run-fallback-policy.test.ts — 3 shards passed, 21 tests passed
  • pnpm docs:check-mdx — 690 files passed
  • git diff --check — passed

The exact failures are visible in pairing follow-up run 28730686889, and each points to one of these three wording mismatches.

@steipete steipete self-assigned this Jul 5, 2026
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS maintainer Maintainer-authored PR labels Jul 5, 2026
@clawsweeper

clawsweeper Bot commented Jul 5, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 5, 2026, 1:39 AM ET / 05:39 UTC.

Summary
The branch updates three docs lines in the environment, cron, and Talk pages to match current source-backed contract wording.

PR surface: Docs 0. Total 0 across 3 files.

Reproducibility: yes. Source inspection shows current main docs do not contain three exact strings asserted by the current docs contract tests; I did not run tests because this review is read-only.

Review metrics: none identified.

Root-cause cluster
Relationship: canonical
Canonical: #100186
Summary: This PR is the current open reconciliation for the docs/test wording mismatch left after two related merged PRs landed with different contract wording.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

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

Next step before merge

  • [P2] No repair lane is needed because the patch already makes the narrow docs-only correction; protected-label merge handling remains with maintainers.

Security
Cleared: The diff changes only Markdown docs wording and does not touch executable code, dependency manifests, workflows, secrets, or package resolution.

Review details

Best possible solution:

Land the narrow docs-only reconciliation through normal maintainer handling once the existing checks remain green.

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

Yes. Source inspection shows current main docs do not contain three exact strings asserted by the current docs contract tests; I did not run tests because this review is read-only.

Is this the best way to solve the issue?

Yes. Updating the three docs lines is the narrowest maintainable fix because the runtime/source-backed tests already define the canonical wording and no runtime behavior needs to change.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

  • add P2: The PR repairs current-main source-backed docs contract failures with limited blast radius and no runtime code change.
  • add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Label justifications:

  • P2: The PR repairs current-main source-backed docs contract failures with limited blast radius and no runtime code change.
  • rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed

PR surface:

Docs 0. Total 0 across 3 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 3 3 3 0
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 3 3 3 0

What I checked:

  • Live PR state: The live PR is open, mergeable, labeled docs/maintainer/size: XS, and changes only docs/automation/cron-jobs.md, docs/help/environment.md, and docs/nodes/talk.md. (b522123a4349)
  • Environment docs mismatch on main: Current main says workspace .env ignores provider credential environment variables from workspace .env files, while the merged environment docs test expects the shorter canonical wording about provider credentials and protected runtime controls from workspace .env. Public docs: docs/help/environment.md. (docs/help/environment.md:11, 53bdac249dbd)
  • Environment test expectation: The current test asserts that docs/help/environment.md contains "OpenClaw ignores provider credentials and protected runtime controls from workspace .env". (src/docs/environment-docs.test.ts:23, 53bdac249dbd)
  • Cron docs mismatch on main: Current main's automation docs still use the alternate local-provider sentence, while the current cron fallback test expects the automation docs to contain the job fallback-chain wording. Public docs: docs/automation/cron-jobs.md. (docs/automation/cron-jobs.md:144, 53bdac249dbd)
  • Cron source and test contract: resolveCronPreflightCandidates builds candidates from resolveCronFallbacksOverride, and the test asserts docs mention the job's configured fallback chain before skipping. (src/cron/isolated-agent/run-fallback-policy.test.ts:431, 53bdac249dbd)
  • Talk docs mismatch on main: Current main's Talk docs still use the prose default form, while the current test expects the table default to use backticked 700 and 900 ms values. Public docs: docs/nodes/talk.md. (docs/nodes/talk.md:94, 53bdac249dbd)

Likely related people:

  • steipete: Git blame and git log tie the current docs lines to the merged docs restoration and broader source-grounded docs rewrite, and this PR is also authored by the same account. (role: recent docs rewrite author and follow-up owner; confidence: high; commits: f7d7148cf047, 53bdac249dbd, b522123a4349; files: docs/help/environment.md, docs/automation/cron-jobs.md, docs/nodes/talk.md)
  • vincentkoc: Git blame ties the canonical environment, Talk, and cron docs-test expectations to the merged test alignment PR. (role: recent docs contract test contributor; confidence: high; commits: 214ee0235981; files: src/docs/environment-docs.test.ts, src/config/talk-defaults.test.ts, src/cron/isolated-agent/run-fallback-policy.test.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.

@clawsweeper clawsweeper Bot added rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P2 Normal backlog priority with limited blast radius. labels Jul 5, 2026
@steipete
steipete merged commit 3cf0d00 into main Jul 5, 2026
82 of 90 checks passed
@steipete
steipete deleted the codex/align-doc-contract-wording branch July 5, 2026 05:41
@steipete

steipete commented Jul 5, 2026

Copy link
Copy Markdown
Contributor Author

Merged via squash.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Improvements or additions to documentation maintainer Maintainer-authored PR P2 Normal backlog priority with limited blast radius. rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. size: XS status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant