openclaw - 💡(How to fix) Fix [Feature]: Clarify and harden OSOP / workflow-contract semantics for reusable specs [1 participants]

Summary

Clarify OSOP as a reusable workflow contract by formalizing data-model semantics, transition rules, idempotency primitives, and audit-grade approval/evidence.

Problem to solve

I have been exploring an OSOP-style workflow contract on top of OpenClaw for recurring workflows with side effects (for example: browser posting flows with verification and evidence requirements).

The current direction is promising, but a few semantic gaps will become production problems if OSOP is treated as a reusable public spec or future runner contract:

• field addressing is ambiguous (for example: post.url, account.correct, browser.profile)
• non-happy-path transitions are underspecified
• non-idempotent steps can still be duplicated operationally
• approval/evidence are not yet structured enough for reliable audit and incident review
• security/capability annotations are descriptive, but not clearly enforceable

In practice, this can lead to inconsistent evaluator behavior, duplicate side effects, and weak post-incident traceability.

Proposed solution

Suggested direction:

1. Normalize the data model

• Pick one model explicitly: nested objects + formal path refs, or flat maps with literal-key semantics
• Reject mixed styles in linting

1. Define transition semantics

• Specify behavior for on_success / on_failure / on_timeout / on_blocked / on_waiting_approval
• Define what partial means when side effects already happened but verification is incomplete

1. Add operational safety primitives

• mutex_key
• idempotency_key
• dedupe_window
• already_done_if

1. Make approval/evidence audit-grade

• typed approval object (approver, approved_at, scope, target steps)
• typed evidence/artifact refs (screenshot, snapshot id, task id, session key, resolved external URL)

1. Clarify runtime trust boundaries

• distinguish model-asserted outputs vs runtime-verified outputs vs externally observed state
• define how capability labels map to runtime/tool classes

Alternatives considered

Alternatives considered:

• Keep OSOP purely as an internal design/SOP artifact and avoid treating it as a runner-facing contract
• Rely on conventions and human review instead of formal semantics
• Push execution safety concerns into each workflow implementation separately

These options are workable short-term, but they do not scale well once multiple workflows or implementations appear.

Impact

Affected: recurring workflows with side effects (posting, messaging, deletions, account writes, browser automation) Severity: medium to high once reused across workflows or implementations Frequency: every time a new workflow author needs to interpret data paths, transitions, or retry behavior Consequence: inconsistent runner behavior, duplicate external actions, incomplete logs, and weaker auditability after incidents

Evidence/examples

Concrete examples of ambiguous fields and semantics:

• post.url
• account.correct
• browser.profile

Without a formal rule, these can be interpreted as either literal dotted keys or nested object paths.

I am opening this as an issue first rather than a PR because the biggest gaps are semantic, not cosmetic. If the direction makes sense, follow-up work could likely be split into:

1. data model / refs
2. execution semantics / state transitions
3. operational safety / auditability

Additional information

Important constraint: if this evolves, it should stay backward-aware for any existing workflow-like docs/examples, but correctness should take priority over preserving ambiguous semantics.