docs: propose Claw composition evidence RFC

[momothemage]

Related: #27
Related: #48
Related: #52
Related: #56
Related: openclaw/clawhub#3359

Additional instructions

MUST: Keep Allow edits from maintainers enabled for this PR so maintainers can help update the branch when needed.

What Problem This Solves

ClawHub's current public Claw summary reports component counts but does not identify the exact Skill and Plugin releases, artifacts, publishers, or publication-time evidence contained in one exact Claw release. It also has no contract separating immutable publication evidence from later scan, moderation, and availability changes.

That leaves users without a bounded pre-download answer to “what is in this Claw?” and risks conflating registry evidence with the applying harness's local dry-run and consent responsibilities.

Why This Change Was Made

This draft defines Claw Composition Evidence, presented to users as an Agent BOM, as an immutable safe snapshot bound to the exact Claw artifact SHA-256. It resolves direct package components at publication and exposes current registry status separately so historical evidence is not rewritten.

The proposal keeps the owner boundary narrow: ClawHub owns package identity, exact registry resolution, publication evidence, and current registry facts; OpenClaw or another applying client remains authoritative for runtime mapping, local effects, plan-integrity consent, mutation, provenance, update, and removal.

A sidecar implementation plan splits the work into schema, publication/storage, API/CLI, web, feed/consumer proof, and later follow-ups.

User Impact

This PR changes RFC text only and does not enable a public API or runtime behavior.

If accepted and implemented, users will be able to inspect exact Claw components and safe MCP, cron, workspace, bootstrap, and profile summaries before download, while seeing publication-time evidence separately from current registry warnings or blocks.

Evidence

• Cross-checked against RFC 0016, draft RFC RFC 0016: consolidate the Claws contract #48, draft RFC RFC 0031: Claw application composition and clients #52, draft RFC docs(claws): define application project lifecycle #56, ClawHub's current Claw schema/publication/feed contracts, and ClawHub #3359.
• Confirmed no existing open RFC PR or issue for Agent BOM / Claw Composition Evidence and no open RFC currently occupies 0030.
• Parsed all 4 Mermaid diagrams with Mermaid 11.16.0.
• Parsed all 7 JSON examples.
• Verified every local Markdown link resolves.
• Ran formatting and whitespace checks:
  • oxfmt --check rfcs/0030-claw-composition-evidence.md rfcs/0030/implementation-plan.md
  • git diff --check

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 7, 2026, 7:42 AM ET / 11:42 UTC.

ClawSweeper review

What this changes

This PR adds a draft RFC and implementation plan for a ClawHub Agent BOM that records artifact-bound package composition evidence separately from current registry status.

Merge readiness

⚠️ Ready for maintainer review - 6 items remain

Keep this draft open: it has a concrete contract contradiction that must be corrected before product-direction review can proceed.

Priority: P3
Reviewed head: 294799a9ae3ac5c562409246c23720f0e697f112
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The RFC is detailed, but its retained contract-boundary defect prevents a higher readiness rating.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes RFC and planning documents only; no runtime behavior is introduced to demonstrate.
Patch quality	🦐 gold shrimp (3/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This PR changes RFC and planning documents only; no runtime behavior is introduced to demonstrate.
Evidence reviewed	4 items	Established CLAW.md boundary: The merged base specification defines the Markdown body as documentation only and forbids consumers from deriving runtime behavior or lifecycle actions from it. Conflicting proposed resource: The PR maps a non-empty CLAW.md body to an implicit managed SOUL.md workspace resource, despite the base contract treating that body as non-executable documentation. Prior blocker remains at this head: The current head is the same SHA as the prior review that raised this concern; no branch change has addressed it.
Findings	1 actionable finding	[P1] Keep the CLAW.md body out of composition resources
Security	Needs attention	Documentation body becomes a managed resource: Treating a package-authored CLAW.md body as an implicit SOUL.md resource conflicts with its non-executable contract and could lead future consumers to treat arbitrary documentation as applied instruction.

How this fits together

The RFC repository defines cross-product contracts before OpenClaw and ClawHub implement them. This proposal would let ClawHub expose pre-download composition evidence while applying clients remain responsible for local planning and consent.

flowchart LR
  A[Claw artifact] --> B[ClawHub publication]
  B --> C[Composition resolver]
  C --> D[Immutable evidence snapshot]
  D --> E[Pre-download inspection]
  F[Current registry status] --> E
  G[Applying client] --> H[Local plan and consent]

Loading

Decision needed

Question	Recommendation
Should maintainers sponsor an independent ClawHub composition-evidence contract now, or defer it until the pending profile and application-composition RFCs establish its dependencies?	Defer pending dependencies: Keep the draft open, correct its safe-projection boundary, and decide its acceptance after the dependent RFC contracts are resolved.

Why: This RFC introduces a new public cross-repository contract whose scope and sequencing cannot be settled by a mechanical documentation correction alone.

Before merge

• Add real behavior proof - Not applicable: This PR changes RFC and planning documents only; no runtime behavior is introduced to demonstrate.
• Keep the CLAW.md body out of composition resources (P1) - The merged CLAW.md contract makes the body documentation only and prohibits deriving lifecycle actions from it. This mapping turns that arbitrary body into an implicit managed SOUL.md resource; remove the resource and any corresponding graph/example references so only manifest-declared workspace entries are represented.
• Resolve security concern: Documentation body becomes a managed resource - Treating a package-authored CLAW.md body as an implicit SOUL.md resource conflicts with its non-executable contract and could lead future consumers to treat arbitrary documentation as applied instruction.
• Resolve merge risk (P1) - As written, the RFC recasts arbitrary documentation-only Markdown as a managed SOUL.md resource, inviting downstream clients to treat it as package-applied instruction.
• Resolve merge risk (P1) - Accepting the public evidence contract before its pending related Claw contracts are resolved could lock an incompatible cross-product boundary.

Findings

• [P1] Keep the CLAW.md body out of composition resources — rfcs/0030-claw-composition-evidence.md:455-457
• [medium] Documentation body becomes a managed resource — rfcs/0030-claw-composition-evidence.md:455

Agent review details

Security

Needs attention: The proposed contract crosses the documentation-to-runtime resource boundary and needs correction before it can safely guide a public API.

Review metrics

Metric	Value	Why it matters
RFC scope	2 documentation files, +1,725 lines	The draft defines a substantial cross-product contract and staged implementation plan.

Merge-risk options

Maintainer options:

1. Correct the safe projection (recommended)
   Remove the CLAW.md-body resource, edge, and examples, and state that documentation-only Markdown cannot create composition or lifecycle records.
2. Pause for API direction
   Leave the draft unmerged until maintainers decide whether any package-authored Markdown may appear in this public evidence contract.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Remove the CLAW.md body workspace-resource mapping and related graph/example references; add an explicit invariant that the body cannot produce a resource, edge, or lifecycle action; then run the RFC document checks.

Technical review

Best possible solution:

Keep the Agent BOM limited to manifest-declared resources and explicitly exclude the CLAW.md body from resources, graph edges, and applying-client lifecycle semantics.

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

Not applicable: this is a documentation-only feature proposal; the contract conflict is directly verifiable from the merged specification and proposed RFC text.

Is this the best way to solve the issue?

No: mapping the CLAW.md body to a managed resource conflicts with its established documentation-only role; retaining only manifest-declared resources is the narrower maintainable design.

Full review comments:

• [P1] Keep the CLAW.md body out of composition resources — rfcs/0030-claw-composition-evidence.md:455-457
  The merged CLAW.md contract makes the body documentation only and prohibits deriving lifecycle actions from it. This mapping turns that arbitrary body into an implicit managed SOUL.md resource; remove the resource and any corresponding graph/example references so only manifest-declared workspace entries are represented.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: not found in the target repository.

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

Labels

Label changes:

• add merge-risk: 🚨 security-boundary: The proposed resource mapping crosses the established boundary between documentation-only content and managed runtime resources.

Label justifications:

• P3: This is a draft product-contract proposal with no current runtime behavior.
• merge-risk: 🚨 compatibility: The RFC proposes a public composition-evidence contract that ClawHub and applying clients would need to preserve.
• merge-risk: 🚨 security-boundary: The proposed resource mapping crosses the established boundary between documentation-only content and managed runtime resources.
• 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: This PR changes RFC and planning documents only; no runtime behavior is introduced to demonstrate.

Evidence

Security concerns:

• [medium] Documentation body becomes a managed resource — rfcs/0030-claw-composition-evidence.md:455
  Treating a package-authored CLAW.md body as an implicit SOUL.md resource conflicts with its non-executable contract and could lead future consumers to treat arbitrary documentation as applied instruction.
  Confidence: 0.98

Acceptance criteria:

• [P1] git diff --check.
• [P1] Manually cross-check rfcs/0030-claw-composition-evidence.md against rfcs/0016/claw-md-v1-spec.md lines 89-93 to confirm the body cannot create a resource or lifecycle action.

What I checked:

• Established CLAW.md boundary: The merged base specification defines the Markdown body as documentation only and forbids consumers from deriving runtime behavior or lifecycle actions from it. (rfcs/0016/claw-md-v1-spec.md:89, 13819ef73d3a)
• Conflicting proposed resource: The PR maps a non-empty CLAW.md body to an implicit managed SOUL.md workspace resource, despite the base contract treating that body as non-executable documentation. (rfcs/0030-claw-composition-evidence.md:455, 294799a9ae3a)
• Prior blocker remains at this head: The current head is the same SHA as the prior review that raised this concern; no branch change has addressed it. (rfcs/0030-claw-composition-evidence.md:455, 294799a9ae3a)
• Current-main status: Current main contains the merged Claws contract but no RFC 0030 composition-evidence proposal, so this distinct contract is not already implemented there. (rfcs/0016/claw-md-v1-spec.md:89, af708f0ddb6f)

Likely related people:

• giodl73-repo: Authored the merged Claws RFC and CLAW.md specification that define the governing documentation-only boundary. (role: base-contract author; confidence: high; commits: 13819ef73d3a; files: rfcs/0016-claws.md, rfcs/0016/claw-md-v1-spec.md)

Rank-up moves

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

• Remove the documentation-body resource mapping and explicitly preserve the existing non-executable CLAW.md boundary.

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 (19 earlier review cycles; latest 8 shown)

• reviewed 2026-08-06T05:20:54.491Z sha 294799a :: needs real behavior proof before merge. :: [P1] Keep the CLAW.md body out of composition resources
• reviewed 2026-08-06T07:19:10.724Z sha 294799a :: needs real behavior proof before merge. :: [P1] Do not turn the CLAW.md body into a resource
• reviewed 2026-08-06T10:15:09.833Z sha 294799a :: needs real behavior proof before merge. :: [P1] Keep the CLAW.md body out of BOM resources
• reviewed 2026-08-06T11:56:20.145Z sha 294799a :: needs real behavior proof before merge. :: [P1] Do not expose the CLAW.md body as a resource
• reviewed 2026-08-06T13:17:50.005Z sha 294799a :: needs real behavior proof before merge. :: [P1] Do not model the CLAW.md body as a SOUL.md resource
• reviewed 2026-08-07T01:52:17.075Z sha 294799a :: needs real behavior proof before merge. :: [P1] Keep the Markdown body out of BOM resources
• reviewed 2026-08-07T04:43:35.981Z sha 294799a :: needs real behavior proof before merge. :: [P1] Do not model the CLAW.md body as SOUL.md
• reviewed 2026-08-07T08:59:15.067Z sha 294799a :: needs real behavior proof before merge. :: [P1] Keep the CLAW.md body out of BOM resources