Docs: initial draft delegation invariants (Confirm/Stop-Takeover/Receipts)#50032
Docs: initial draft delegation invariants (Confirm/Stop-Takeover/Receipts)#50032wicky-AntX wants to merge 11 commits intoopenclaw:mainfrom
Conversation
Docs-only initial draft for discussion: minimal delegation invariants (Confirm/Stop-Takeover/Receipts) + stable hook points.
openclaw-barnacle
bot
added
docs
Greptile SummaryThis docs-only PR adds Two issues need to be resolved before this can merge:
Confidence Score: 2/5
Prompt To Fix All With AIThis is a comment left during a code review.
Path: docs/delegation-invariants.md
Line: 47-55
Comment:
**Unclosed JSON code fence**
The code block opened with ` ```json ` on line 47 is never closed — there is no closing ` ``` ` before the file ends. This causes the Markdown renderer (and Mintlify) to treat everything after the opening fence as raw code, breaking the document's visual formatting.
Add a closing fence after the closing `}`:
```suggestion
**Example (minimal JSON):**
```json
{
"type": "confirm",
"scope": "purchase",
"limits": { "max_amount_usd": 200, "merchant_allowlist": ["United Airlines"] },
"ttl_seconds": 900,
"revocable": true,
"risk_level": "high"
}
```
```
How can I resolve this? If you propose a fix, please make it concise.
---
This is a comment left during a code review.
Path: docs/delegation-invariants.md
Line: 28-55
Comment:
**Stop(Takeover) and Receipts sections are missing**
The PR title, description, and the document's own header all promise three invariant primitives — **Confirm**, **Stop/Takeover**, and **Receipts** — but the file ends after the Confirm section. The `### 2) STOP/TAKEOVER` and `### 3) RECEIPTS` sections (with their MUST/SHOULD fields and minimal JSON examples) are completely absent.
Shipping an explicitly incomplete spec risks reviewers or downstream contributors treating the Confirm-only content as the finalized "thin waist", leaving Stop/Takeover halt semantics and Receipt accountability fields undefined. Please add the two missing sections (or, if intentional, call them out clearly as `TODO` stubs so readers know they are forthcoming).
How can I resolve this? If you propose a fix, please make it concise.Last reviewed commit: "Create delegation-in..." |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 105dc4d926
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
docs/delegation-invariants.md
Outdated
| **Example (minimal JSON):** | ||
| ```json | ||
| { | ||
| "type": "confirm", |
There was a problem hiding this comment.
If this draft is meant to define the three primitives named in the title and in the “three primitives” claim above, the file currently stops immediately after the first CONFIRM example, with no STOP/TAKEOVER or RECEIPT sections at all. That leaves the spec internally inconsistent and makes it unclear whether those two invariants were intentionally omitted or accidentally dropped from the commit.
Useful? React with 👍 / 👎.
Complete the docs-only draft by adding Stop/Takeover and Receipt primitives, plus closing JSON code fences so the document renders correctly. No runtime changes.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 326918d508
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 754f5de5e8
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
docs/delegation-invariants.md
Outdated
| ### Required fields (minimal) | ||
|
|
||
| - `confirm_id` | ||
| - `timestamp` (ISO-8601) | ||
| - `scope` (what is authorized) | ||
| - `limits` (budget/cap/etc.) | ||
| - `ttl_seconds` | ||
| - `revocable` (boolean) | ||
| - `risk_level` (e.g., `"low" | "medium" | "high"`) |
There was a problem hiding this comment.
If this invariant is used outside a single-user session, the CONFIRM schema never records who granted the authority. A later RECEIPT can point to confirm_id, but auditors and policy hooks still cannot tell whether the approval came from the end user, an admin, or another delegate without falling back to runtime-specific session state. That undermines the document's goal of making execution authority portable across runtimes, so the minimal fields need a grantor/principal reference.
Useful? React with 👍 / 👎.
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5184475aff
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
docs/delegation-invariants.md
Outdated
| **Example (minimal JSON):** | ||
| ```json | ||
| { |
There was a problem hiding this comment.
The current draft never shows a CONFIRM payload that actually satisfies the required field list: the first JSON block is truncated after capabilities, and the follow-on block omits the required confirm_id and timestamp. Anyone copying the advertised “minimal JSON” example will produce confirms that cannot be correlated to receipts or anchored to a TTL start time.
Useful? React with 👍 / 👎.
docs/delegation-invariants.md
Outdated
| ```json | ||
| { | ||
| "type": "confirm", | ||
| "scope": "purchase", |
There was a problem hiding this comment.
scope structured in the CONFIRM example
Above this example, scope is defined as an object containing at least workflow_id, plus optional step_ids/targets/capabilities. Here it becomes the bare string "purchase", which creates two incompatible wire shapes for the same field and drops the workflow/step binding the rest of the spec relies on.
Useful? React with 👍 / 👎.
docs/delegation-invariants.md
Outdated
| **Example (minimal JSON):** | ||
| ```json | ||
| { | ||
| "type": "confirm", |
There was a problem hiding this comment.
type value for CONFIRM
This example uses "type": "confirm", while the earlier block and the other primitives use uppercase names (CONFIRM, STOP, RECEIPT). If runtimes dispatch on literal event-type strings, the doc now defines two non-interoperable values for the same primitive and readers copying this block will serialize a different protocol variant.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 062c75783c
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9bce050c8b
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cb62f06097
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
@steipete @vincentkoc @obviyus @gumadeiras CI failure is unrelated to this docs-only change. |
|
Please don’t spam-ping multiple maintainers at once. Be patient, or join our community Discord for help: https://discord.gg/clawd |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2a617a34d8
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
Checks are green now ✅ If there’s interest, I can help coordinate a short, time-boxed discussion thread to collect input on the minimal fields + hook points. |
|
I added a hard TL;DR + Chromebook analogy + cloud fast-path rationale in the issue: #48629 |
1 participant
Docs-only PR (no code changes).
Summary
Change Type (select all)
Scope (select all touched areas)
Linked Issue/PR
User-visible / Behavior Changes
None (docs-only).
Security Impact (required)
If any Yes, explain risk + mitigation: N/A (docs-only)
Repro + Verification
Environment
Steps
N/A (docs-only)
Expected
N/A
Actual
N/A
Evidence (attach at least one)
Human Verification (required)
Review Conversations
Compatibility / Migration
If yes, exact upgrade steps: N/A
Failure Recovery (if this breaks)
docs/delegation-invariants.mdRisks and Mitigations