RFC 0016: consolidate the Claws contract

[giodl73-repo]

Supersedes #52 and #56 by folding their still-relevant contracts into RFC 0016.

What Problem This Solves

The Claws contract was split across overlapping RFC drafts while package, profile, bootstrap, extension, heartbeat, memory, metadata, and project behavior continued to converge.

Why This Change Was Made

This revision makes draft RFC 0016 and its normative sidecars the single schema-v1 contract. It incorporates the application-project and OpenClaw-profile specifications while preserving host ownership of runtime configuration, secrets, shared plugins, and lifecycle state.

User Impact

Implementers and reviewers get one coherent draft specification instead of reconciling conflicting requirements across RFC #48, #52, and #56.

Evidence

• All five RFC files aligned on draft status and canonical agents.entries
• Plugin cleanup and cross-platform golden-byte requirements reconciled
• Final independent reviews with GPT-5.6 Sol, GPT-5.6 Terra, and Claude Opus 5
• git diff --check

Final implementation proof

• RFC head acf99d988d90b8d106a4c1d22f66b139bfb02def
• OpenClaw implementation head f69dcea5cf28697720593113092d4e323fa583e2: 87 exact-head checks passed, plus the full local src/claws suite passed 452 tests with 1 skip.
• ClawHub implementation head 9955d795c7e997d0fbedf7df23b29651757ad0de: full CI passed.
• Cross-repository pinned-parser proof passed against OpenClaw f8c0e1b8325b1fc36e039cf357a2c4602f76d5aa.

[omarshahine]

This addendum finalizes portable per-agent tool, filesystem, and memory-search fields in experimental Claw schema v1 and extends the normative lifecycle/consent contract. These are the right documents to own that contract, but the proposed shape currently conflicts with canonical OpenClaw configuration and with its own security and disclosure guarantees.

LOC: +201/-19 (3 files)

Findings

1. Blocking: use the canonical per-agent memory shape before finalizing v1.

   rfcs/0016-claws.md:425 shows generated agent config using memorySearch, and rfcs/0016/claw-md-v1-spec.md:178 says these fields map directly to existing per-agent configuration. Current OpenClaw instead defines per-agent memory at memory.search (src/config/types.agents.ts:125-128) and explicitly treats agents.*.memorySearch as dead config.

   Prefer the canonical nested shape before graduation. If a distinct portable spelling is intentional, both sidecars must normatively define translation and output shape instead of claiming direct mapping.

2. Blocking: define the actual host-policy upper bound.

   rfcs/0016-claws.md:371-375 and rfcs/0016/claw-package-v1-spec.md:307-310 say global/operator policy cannot be widened by a Claw. Runtime, however, selects the per-agent profile over the global profile, and per-agent filesystem policy can override global workspaceOnly.

   Please choose and state the real contract: either enforce a non-overridable host ceiling during planning/apply, or say global profile/filesystem values are inherited defaults and enumerate the actual non-bypassable upper-bound layers such as hard allow/deny policy and sandbox enforcement.

3. Blocking: reconcile the Control UI disclosure contract with normative consent.

   rfcs/0016-claws.md:980-985 says the browser receives a redacted plan projection rather than the manifest. The normative package sidecar requires the applying client to make the exact grouped manifest available before consent and to disclose literal MCP arguments plus cron message/delivery behavior (rfcs/0016/claw-package-v1-spec.md:265-287).

   Give an authorized UI an expandable exact validated manifest and all required effects while withholding secret values and source-file bytes, or amend the normative sidecar to define a sufficient safe projection and exactly what may be omitted.

4. P2: separate RFC acceptance from experimental schema graduation.

   rfcs/0016-claws.md:7 remains status: draft with no implementation issue even though RFC RFC: Claws #27 is merged. The repository lifecycle says acceptance uses status: accepted plus an implementation issue. Keep the sidecars explicitly experimental, but make the parent RFC lifecycle state unambiguous.

Best-fix verdict: correct owner and timing, but internally inconsistent as written. Align the memory and policy contracts first, then keep detailed Control UI implementation mechanics in a non-normative plan or linked issue after its disclosure contract is resolved.

Specs/contracts read: full RFC 0016 and both normative sidecars; RFC repository guidance and #27 discussion; linked implementation PR #112773; canonical OpenClaw memory config, tool-policy, filesystem-policy, and security-audit owners.

Remaining uncertainty: this is a docs/spec review. I did not run contributor-controlled implementation code, and I did not inspect every line of the separate draft Control UI implementation PRs.

[giodl73-repo]

Added a non-blocking post-merge roadmap at signed head 6b9c2fc: first-party starter Claws and end-to-end product validation, selective export and publication authoring, explicit experimental graduation, a later separate cross-harness portability proposal (npx claws --agent ...), and evidence-driven lifecycle follow-ups.

@clawsweeper re-review

[clawsweeper]

🦞🧹
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.

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30011159066
• Updated: 2026-07-23T13:26:28.784Z

[giodl73-repo]

Portability feedback is incorporated at signed head 8ac0203: the Claw manifest is now a harness-agnostic core with opaque string metadata, while metadata.openclaw.config points to a strict package-local OpenClaw profile. Other harnesses may ignore that key or define their own namespaced pointer; validators only interpret profile-pointer keys they recognize. The sidecar is integrity-bound and never becomes ordinary OpenClaw configuration.

Implementation is at openclaw/openclaw#112773. Final Codex review found no actionable correctness issues.

[giodl73-repo]

Aligned the RFC and sidecar spec with the reviewed implementation at signed head fa31caafedd4: heartbeat.skipWhenBusy is no longer part of the profile contract, and metadata.openclaw.config now explicitly requires forward-slash package-relative syntax with backslashes invalid. This keeps the portable manifest, OpenClaw profile, implementation, and ClawHub validation contract consistent.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 14, 2026, 9:29 AM ET / 13:29 UTC.

ClawSweeper review

What this changes

Consolidates RFC 0016 into five Markdown specifications covering the portable package, prompt, OpenClaw profile, native bootstrap, and project authoring lifecycle.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep open for an explicit maintainer product-direction decision: this is a coherent, documentation-only consolidation of an experimental Claws contract, but it establishes compatibility- and security-relevant normative guidance beyond what the current RFC repository has accepted.

Priority: P2
Reviewed head: acf99d988d90b8d106a4c1d22f66b139bfb02def
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The patch is a coherent, well-scoped documentation consolidation with no concrete line-level defect found, pending maintainer direction on publishing the contract.
Proof confidence	🌊 off-meta tidepool	Not applicable: Not applicable: all changed files are RFC Markdown; the linked implementation checks are useful context but are not required real-behavior proof for this documentation-only patch.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: Not applicable: all changed files are RFC Markdown; the linked implementation checks are useful context but are not required real-behavior proof for this documentation-only patch.
Evidence reviewed	5 items	Current-main baseline: Current main contains the earlier RFC 0016 draft and its two original sidecars; it does not contain this PR's project or OpenClaw-profile contracts. Proposed contract scope: The PR adds the project and OpenClaw profile specifications and revises the existing RFC and two sidecars, for five RFC Markdown files total. RFC lifecycle policy: The repository says RFCs should not merge while draft and accepted RFCs need an implementation issue; this PR deliberately retains draft status, so its publication requires maintainer intent.
Findings	None	None.
Security	None	None.

How this fits together

Claws package one purpose-built agent with its workspace, dependencies, MCP servers, and scheduled work. The RFC documents how authored package inputs are validated and handed to OpenClaw's existing lifecycle owners for planning, consent, and application.

flowchart LR
  A[Claw project sources] --> B[Validation and deterministic build]
  B --> C[Immutable package artifact]
  C --> D[OpenClaw inspection and plan]
  D --> E[Consent and owner delegation]
  E --> F[Agent workspace and provenance]
  C --> G[Registry publication and discovery]

Loading

Decision needed

Question	Recommendation
Should RFC 0016's expanded portable package, OpenClaw profile, and authoring contracts be published as the repository's single experimental Claws reference now?	Sponsor the experimental contract: Confirm the consolidated draft as the canonical experimental reference after maintainers verify it against the named authoritative implementation.

Why: The patch is a large normative product contract with compatibility and consent implications; source review can establish coherence, but cannot choose whether this is the intended stable direction for the project.

Before merge

• Add real behavior proof - Not applicable: Not applicable: all changed files are RFC Markdown; the linked implementation checks are useful context but are not required real-behavior proof for this documentation-only patch.
• Resolve merge risk (P1) - Merging would make one experimental document set the reference for package, profile, and lifecycle behavior; maintainers need to confirm its exact alignment with the authoritative OpenClaw implementation before treating it as canonical.
• Resolve merge risk (P1) - The proposed profile governs tool, filesystem, memory, plugin, bootstrap, and consent semantics, so any specification drift could become a compatibility or security-boundary problem for later implementers.
• Resolve merge risk (P1) - The RFC remains draft while repository policy says draft RFCs should not merge, requiring an explicit decision on whether this amendment is ready to publish.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC surface	5 Markdown files affected; 2 new sidecars	The patch changes the central RFC plus all implementation-facing contract layers, so review needs cross-document agreement.
Documentation delta	+765, -302 lines	This is a substantial normative rewrite rather than a narrow editorial adjustment.

Root-cause cluster

Relationship: canonical
Canonical: #48
Summary: This PR explicitly folds the remaining contracts from two closed, unmerged RFC drafts into RFC 0016.

Members:

• superseded: RFC 0031: Claw application composition and clients #52 - Its own status states that it was waiting for this RFC, and the current PR body says it folds the still-relevant contract into RFC 0016.
• superseded: docs(claws): define application project lifecycle #56 - Its stated project-lifecycle material is incorporated as the new project sidecar in this PR, and its branch was closed unmerged.

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

Merge-risk options

Maintainer options:

1. Confirm contract compatibility (recommended)
   Require maintainer confirmation that the profile, prompt, bootstrap, and project rules match the intended OpenClaw compatibility contract before merging.
2. Defer consolidation
   Pause this PR if the repository does not yet want these experimental interfaces to be its canonical contract.

Technical review

Best possible solution:

Have the responsible maintainer confirm that the unified draft is the intended experimental contract and that its named OpenClaw behavior is the canonical reference; keep later graduation behind the repository's accepted-RFC and implementation-tracker process.

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

Not applicable: this PR changes RFC Markdown rather than reporting a runtime failure; the relevant review path is cross-document and implementation-contract verification.

Is this the best way to solve the issue?

Unclear until a maintainer confirms product direction. Consolidation is a maintainable way to remove the closed overlapping drafts, but publishing it as the canonical experimental contract requires explicit ownership approval.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P2: This is a substantial but non-emergency experimental contract decision affecting future implementers.
• merge-risk: 🚨 compatibility: The proposed package, profile, prompt, and bootstrap rules define behavior that other Claws implementations may follow.
• merge-risk: 🚨 security-boundary: The contract specifies consent, tool, filesystem, plugin, MCP, and bootstrap boundaries that must remain aligned with host enforcement.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Not applicable: all changed files are RFC Markdown; the linked implementation checks are useful context but are not required real-behavior proof for this documentation-only patch.

Evidence

What I checked:

• Current-main baseline: Current main contains the earlier RFC 0016 draft and its two original sidecars; it does not contain this PR's project or OpenClaw-profile contracts. (rfcs/0016-claws.md:7, af708f0ddb6f)
• Proposed contract scope: The PR adds the project and OpenClaw profile specifications and revises the existing RFC and two sidecars, for five RFC Markdown files total. (rfcs/0016/openclaw-profile-v1-spec.md:1, acf99d988d90)
• RFC lifecycle policy: The repository says RFCs should not merge while draft and accepted RFCs need an implementation issue; this PR deliberately retains draft status, so its publication requires maintainer intent. (README.md:80, af708f0ddb6f)
• Feature provenance: The original Claws RFC on current main dates to the merged RFC commit, which git blame attributes to the same feature author. (rfcs/0016-claws.md:1, 13819ef73d3a)
• Authoritative implementation dependency: The proposed OpenClaw profile explicitly identifies shipped OpenClaw behavior as authoritative, making exact implementation alignment a relevant maintainer check. (rfcs/0016/openclaw-profile-v1-spec.md:5, acf99d988d90)

Likely related people:

• giodl73-repo: Introduced the Claws RFC now on main and authored both commits in this consolidated contract revision. (role: original RFC author and recent contract contributor; confidence: high; commits: 13819ef73d3a, cbfbf730d8cb, acf99d988d90; files: rfcs/0016-claws.md, rfcs/0016/claw-package-v1-spec.md, rfcs/0016/claw-md-v1-spec.md)
• omarshahine: Prior review discussion identified and tracked consent, bootstrap-collision, and RFC-lifecycle requirements on this RFC surface. (role: contract reviewer; confidence: medium; files: rfcs/0016-claws.md, rfcs/0016/claw-package-v1-spec.md, rfcs/0016/openclaw-profile-v1-spec.md)

Rank-up moves

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

• Obtain explicit maintainer confirmation that this draft is the intended canonical experimental Claws contract.

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

• reviewed 2026-08-09T23:04:43.409Z sha 018297f :: needs real behavior proof before merge. :: [P1] Persist the resolved tool-profile capability set | [P2] Reject BOOTSTRAP.md ancestor and descendant paths
• reviewed 2026-08-09T23:19:26.972Z sha 018297f :: needs real behavior proof before merge. :: [P1] Preserve consent across built-in tool-profile changes | [P2] Reject hierarchical BOOTSTRAP.md workspace destinations
• reviewed 2026-08-10T01:41:22.459Z sha 9500d9f :: needs real behavior proof before merge. :: none
• reviewed 2026-08-10T05:11:04.188Z sha c8e10d2 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-10T22:49:33.934Z sha 19fe123 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-10T23:03:53.468Z sha 19fe123 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-13T20:22:18.521Z sha acf99d9 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-14T04:30:48.118Z sha acf99d9 :: needs real behavior proof before merge. :: none

[giodl73-repo]

The implementation evidence requested by the latest ClawSweeper review is now available: openclaw/openclaw#112773 merged as e9b3252ae8e5cad8be0b7d3d209365c5516aa1b8. Its final exact-head proof covered the portable manifest pointer, package-local OpenClaw profile parsing, profile integrity binding, agent settings projection, and focused lifecycle/profile/export tests. The broader experimental Claws lifecycle and CLAW.md support are also merged on current OpenClaw main.

The final RFC head retains host authority and exact consent disclosure as normative constraints; it does not make the browser projection the authority or permit a Claw profile to bypass host enforcement.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30588005151
• Updated: 2026-07-30T22:41:49.062Z

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31347822964
• Updated: 2026-08-10T01:43:08.712Z

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31358263227
• Updated: 2026-08-10T05:20:25.937Z

[giodl73-repo]

Exact head 19fe1233570e9074216bd7be8e5c7f1518b38ba2 finalizes the bounded MCP authority, non-whitespace prompt, and exact 2 MiB UTF-8 native bootstrap contract.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/31440990919
• Updated: 2026-08-10T23:06:07.932Z

[giodl73-repo]

Final implementation evidence is now linked in the RFC body:

• OpenClaw exact-head CI: https://github.com/openclaw/openclaw/actions/runs/31768323815/job/94671305995
• ClawHub full CI: https://github.com/openclaw/clawhub/actions/runs/31769430527
• Real pinned OpenClaw parser proof: https://github.com/openclaw/clawhub/actions/runs/31769430527/job/94672069310

This proves both sides of the draft contract on their published heads.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.