a2a-Market-Order-State-Machine

Define order lifecycle states, transition guards, and recovery paths for A2A transactions. Use when implementing order orchestration from quote acceptance th...

Security Scan

This is an instruction-only scaffold for an A2A order state machine that requests no credentials or installs and is internally consistent, though it references runtime code/tests that are not bundled with the skill.

Purpose & Capability

The name and description match the SKILL.md content: it describes order lifecycle states, transitions, and recovery. There are no unrelated required binaries, env vars, or config paths. One minor note: the SKILL.md claims an implementation exists in a local runtime package (paths and tests cited) but no code files are included in the skill bundle; this is a documentation/packaging mismatch rather than a coherence/security problem.

Instruction Scope

The instructions are high-level design guidance (states, events, suggested project layout, MVP contracts). They do not instruct the agent to read system files, fetch secrets, call external endpoints, or execute commands. The references to running `npm test` and runtime file paths are informational and do not direct the agent to perform actions outside the stated scope.

Install Mechanism

No install spec provided (instruction-only). Nothing will be downloaded or written to disk by the skill itself.

Credentials

The skill does not request any environment variables, credentials, or config paths. This is proportionate for a design/scaffold skill. Implementers should note that when they implement payment or reputation integrations in their own code, those integrations will require appropriate credentials handled outside this skill.

Persistence & Privilege

The skill is not marked always:true and does not appear to request or modify persistent agent or system configuration. Autonomous invocation is allowed by platform default but the skill's instructions do not give it special persistence or elevated privileges.

Assessment

This skill is a design scaffold only—it contains high-level requirements, state names, and suggested file layout but no code or install steps. It does not ask for credentials or attempt to run commands. Before adopting it, confirm whether you need an actual implementation: the SKILL.md references a local runtime package and tests that are not bundled here, so you should review the real runtime code (and any payment/reputation integration code) in your repository to ensure credential handling and external calls are implemented securely. If you expect the skill to provide runnable code, request the implementation or a trusted package; otherwise using this as a spec/template is reasonable and low-risk.

Define the canonical order lifecycle and transition guard framework.

Current status: first-release scaffold for early protocol compatibility.

Scope

• Model order states from creation to completion/cancelation.
• Enforce legal transitions with guard checks and side effects.
• Integrate payment and reputation triggers into state changes.

Suggested Project Layout

• app/domain/order/order_state.py
• app/domain/order/order_aggregate.py
• app/application/usecases/transition_order.py
• app/application/services/order_event_publisher.py

Minimum Contracts (MVP P0)

1. create_order(intent_id, accepted_quote_id) initializes order in CREATED.
2. transition(order_id, action, actor, payload) validates and applies state move.
3. get_order_timeline(order_id) returns ordered transition history.
4. recover_pending_orders(now_ts) handles timeout and stuck states.

Base States

• CREATED
• NEGOTIATING
• PAYMENT_PENDING
• PAID
• FULFILLING
• COMPLETED
• CANCELED
• FAILED

Events

• Emit ORDER_CREATED at initialization.
• Emit ORDER_COMPLETED when terminal success is reached.
• Emit reputation update trigger after completion/cancel resolution.

Implementation Backlog

• Add compensation transitions for partial fulfillment failures.
• Add deterministic replay from event store snapshots.

Runtime Implementation

• Status: implemented in local runtime package.
• Primary code paths:
• runtime/src/domain/order-state-machine.js
• Validation: covered by runtime/tests and npm test in runtime/.