Skip to content

Docs: add policy rule reference tables#85795

Merged
giodl73-repo merged 1 commit into
openclaw:mainfrom
giodl73-repo:policy-doc-reference-tables
May 23, 2026
Merged

Docs: add policy rule reference tables#85795
giodl73-repo merged 1 commit into
openclaw:mainfrom
giodl73-repo:policy-doc-reference-tables

Conversation

@giodl73-repo

@giodl73-repo giodl73-repo commented May 23, 2026

Copy link
Copy Markdown
Contributor

Summary

This docs-only follow-up upgrades the policy CLI page with a normalized field reference for every current policy category, including the tool-posture section that is now on main from #85482.

The goal is to make the operator-facing policy contract easier to review: each table maps a policy.jsonc field to the OpenClaw config or workspace evidence it observes and the reason an operator would use it.

Verification

  • pnpm docs:list
  • pnpm exec oxfmt --check --threads=1 docs/cli/policy.md
  • pnpm docs:check-mdx docs/cli/policy.md
  • git diff --check
  • codex review --base origin/main

Real behavior proof

Behavior addressed: Documentation-only reference coverage for existing Policy plugin rule fields.
Real environment tested: WSL checkout at /root/src/openclaw-policy-doc-reference-tables on Ubuntu-24.04.
Exact steps or command run after this patch: Ran docs listing, MDX validation, Markdown formatting, whitespace checks, and Codex review against the docs-only diff from origin/main.
Evidence after fix: docs/cli/policy.md now includes field-reference tables for channels, MCP servers, model providers, network, Gateway, agent workspace, secrets, auth profiles, tool metadata, and tool posture.
Observed result after fix: Docs checks, formatting checks, whitespace checks, and Codex review pass with no accepted/actionable findings.
What was not tested: Runtime policy behavior; this PR changes documentation only.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation extensions: policy size: XL maintainer Maintainer-authored PR labels May 23, 2026
@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge.

Latest ClawSweeper review: 2026-05-23 18:44 UTC / May 23, 2026, 2:44 PM ET.

Workflow note: Future ClawSweeper reviews update this same comment in place.

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.

PR Surface
Source +810, Tests +539, Docs +138. Total +1487 across 7 files.

View PR surface stats
Area Files Added Removed Net
Source 4 817 7 +810
Tests 1 539 0 +539
Docs 2 143 5 +138
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 7 1499 12 +1487

Summary
The branch adds policy rule reference tables to the policy CLI docs and, because it is stacked, also carries the parent tool-posture policy conformance source, tests, and docs.

Reproducibility: not applicable. this is a stacked policy/docs PR rather than a bug report. The review used the PR body, related parent context, current-main source, and the local PR commits instead of a failing reproduction path.

PR rating
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Summary: The patch has sufficient proof and no blocking finding, with merge readiness mainly gated on parent sequencing and policy contract review.

Rank-up moves:

  • Land or close the parent policy tool-posture PR, then rebase this follow-up so the diff is docs-focused.
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.

Real behavior proof
Sufficient (live_output): The PR body gives exact docs validation commands, and the linked parent context includes redacted live CLI output for the carried tool-posture policy behavior.

Risk before merge

  • Merging this branch directly would also land the still-open parent policy tool-posture implementation from Policy: add tool posture conformance checks #85482 as part of this docs-labeled follow-up.
  • The carried parent defines new operator-facing policy.jsonc fields for security-sensitive tool posture, so maintainers need to accept the compatibility and security-boundary contract before merge.

Maintainer options:

  1. Land parent first, then rebase (recommended)
    Hold this follow-up until Policy: add tool posture conformance checks #85482 is merged or rejected, then rebase so the remaining diff is docs-focused.
  2. Merge as a combined policy change
    Maintainers can intentionally treat this branch as the combined feature and docs landing if they also accept the parent policy contract risks.
  3. Pause if the policy direction changes
    If the parent policy contract changes or is rejected, pause or close this follow-up and ask for a docs-only branch matching the chosen direction.

Next step before merge
Maintainer review should decide parent sequencing and the policy contract/security-boundary risk; there is no narrow automated repair to queue.

Security
Cleared: No concrete supply-chain, secret-handling, or permission regression was found in the diff; the security-sensitive policy contract still needs maintainer acceptance.

Review details

Best possible solution:

Settle the parent policy tool-posture PR first, then rebase this follow-up so reviewers can evaluate the policy reference tables as the remaining change.

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

Not applicable: this is a stacked policy/docs PR rather than a bug report. The review used the PR body, related parent context, current-main source, and the local PR commits instead of a failing reproduction path.

Is this the best way to solve the issue?

Yes for the docs direction, but not as a direct merge while it carries the parent feature. The maintainable path is to decide the parent policy contract first and then land this as a rebased docs follow-up.

Label justifications:

  • P2: This is a normal-priority policy/docs improvement with limited blast radius but real maintainer sequencing risk.
  • merge-risk: 🚨 compatibility: Direct merge would introduce new policy fields and check outputs from the still-open parent PR.
  • merge-risk: 🚨 security-boundary: The carried policy checks describe security-sensitive tool posture and must match the maintainer-approved security contract.
  • rating: 🐚 platinum hermit: Current PR rating is 🐚 platinum hermit because proof is 🐚 platinum hermit, patch quality is 🐚 platinum hermit, and The patch has sufficient proof and no blocking finding, with merge readiness mainly gated on parent sequencing and policy contract review.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body gives exact docs validation commands, and the linked parent context includes redacted live CLI output for the carried tool-posture policy behavior.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR body gives exact docs validation commands, and the linked parent context includes redacted live CLI output for the carried tool-posture policy behavior.

What I checked:

  • Protected maintainer handling: The provided live GitHub context lists the maintainer label on this PR, which prevents conservative cleanup closing and requires explicit maintainer handling.
  • Stacked parent is still open: The PR body says it is stacked on Policy: add tool posture conformance checks #85482, and the related-item context shows that parent policy tool-posture PR is still open.
  • Actual branch surface includes parent implementation: The branch diff against its recorded base adds 1,499 lines across policy docs, source, and tests, so this is not a docs-only merge candidate until the parent lands or the branch is rebased. (042bd01c14ce)
  • Parent policy checks carried by this branch: The carried parent commit registers the new tool-posture policy health checks, including profile, filesystem, exec, elevated, and required-deny checks. (extensions/policy/src/doctor/register.ts:161, 87bb37325b4a)
  • Docs table change is the follow-up commit: The head commit adds the policy rule reference section, including field tables for tool posture and the other policy categories. Public docs: docs/cli/policy.md. (docs/cli/policy.md:168, 042bd01c14ce)
  • Current main did not alter the touched policy files since the PR base: No output for the touched policy/docs files, so current main has not independently changed those files since the PR's recorded base. (edbd8333511c)

Likely related people:

  • steipete: In this shallow/grafted checkout, git blame and git log --follow for the central policy docs/code all trace current-main lines back to Peter Steinberger's grafted import commit, so this is the only concrete current-main routing signal available. (role: current-main source-history signal; confidence: low; commits: 9c26b87114c9; files: docs/cli/policy.md, extensions/policy/src/doctor/register.ts, extensions/policy/src/policy-state.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against edbd8333511c.

@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary 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. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. labels May 23, 2026
@clawsweeper

clawsweeper Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor

ClawSweeper PR egg

✨ Hatched: 🥚 common Sunspot Diff Drake

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

  • Merged PRs are hatchable.
  • Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
  • Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: finds missing screenshots.
Image traits: location CI tidepool; accessory review stamp; palette seafoam, black, and opal; mood sleepy but ready; pose sitting proudly on a smooth stone; shell brushed metal shell; lighting gentle morning glow; background small green status lights.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Sunspot Diff Drake in ClawSweeper.

What is this egg doing here?
  • Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
  • The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
  • Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
  • The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
  • Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

@giodl73-repo giodl73-repo force-pushed the policy-doc-reference-tables branch from 042bd01 to 05b9839 Compare May 23, 2026 23:56
@giodl73-repo giodl73-repo merged commit 4ffbd07 into openclaw:main May 23, 2026
37 of 39 checks passed
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 24, 2026
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 24, 2026
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 24, 2026
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 24, 2026
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 26, 2026
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 26, 2026
SebTardif pushed a commit to SebTardif/openclaw that referenced this pull request May 26, 2026
jameslcowan pushed a commit to jameslcowan/openclaw that referenced this pull request Jun 2, 2026
SYU8384 pushed a commit to SYU8384/openclaw that referenced this pull request Jun 3, 2026
sablehead pushed a commit to sablehead/openclaw that referenced this pull request Jun 10, 2026
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 extensions: policy maintainer Maintainer-authored PR merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. P2 Normal backlog priority with limited blast radius. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary 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