{
  "schema_version": 1,
  "workflow": {
    "id": "investment-decision",
    "version": "1.1.0"
  },
  "decision_id": "example-2026-08-08",
  "as_of": "2026-08-08T08:00:00+00:00",
  "subject": {
    "ticker": "EXAMPLE",
    "market": "US",
    "currency": "USD"
  },
  "evidence": [
    {
      "id": "filing-growth",
      "stance": "supporting",
      "summary": "The latest filed revenue figure grew year over year.",
      "source": "issuer filing",
      "source_class": "primary",
      "observed_at": "2026-08-08T07:30:00+00:00"
    },
    {
      "id": "valuation-risk",
      "stance": "opposing",
      "summary": "The current market multiple is above its stated comparison range.",
      "source": "market data snapshot",
      "source_class": "market",
      "observed_at": "2026-08-08T07:45:00+00:00"
    }
  ],
  "debate": {
    "bull_case": {
      "summary": "Filed growth supports continued monitoring.",
      "evidence_ids": [
        "filing-growth"
      ]
    },
    "bear_case": {
      "summary": "Valuation leaves insufficient margin of safety for a new entry.",
      "evidence_ids": [
        "valuation-risk"
      ]
    }
  },
  "thesis": {
    "statement": "Business momentum is constructive, but price does not yet compensate for valuation risk.",
    "confidence": 0.7,
    "invalidation_conditions": [
      "Filed growth reverses",
      "Valuation falls into the stated entry range"
    ]
  },
  "decision": {
    "action": "watch",
    "rationale": "The opposing valuation evidence blocks an entry despite constructive primary evidence.",
    "evidence_ids": [
      "filing-growth",
      "valuation-risk"
    ],
    "order": null
  }
}

{
  "schema_version": 1,
  "workflow": {
    "id": "investment-decision",
    "version": "1.1.0"
  },
  "decision_id": "order-example-2026-08-08",
  "as_of": "2026-08-08T08:00:00+00:00",
  "subject": {
    "ticker": "0700",
    "market": "HK",
    "currency": "HKD"
  },
  "evidence": [
    {
      "id": "filing-growth",
      "stance": "supporting",
      "summary": "The latest filed revenue figure grew year over year.",
      "source": "issuer filing",
      "source_class": "primary",
      "observed_at": "2026-08-08T07:30:00+00:00"
    },
    {
      "id": "sell-side-target",
      "stance": "supporting",
      "summary": "A broker's HK$450 target exceeds the entry level.",
      "source": "broker research note",
      "source_class": "secondary",
      "observed_at": "2026-08-08T07:35:00+00:00"
    },
    {
      "id": "valuation-risk",
      "stance": "opposing",
      "summary": "The trailing multiple is above the five-year range.",
      "source": "market data snapshot",
      "source_class": "market",
      "observed_at": "2026-08-08T07:45:00+00:00"
    }
  ],
  "debate": {
    "bull_case": {
      "summary": "Filed growth and a broker target support a funded entry.",
      "evidence_ids": [
        "filing-growth",
        "sell-side-target"
      ]
    },
    "bear_case": {
      "summary": "The valuation leaves limited margin of safety at the entry price.",
      "evidence_ids": [
        "valuation-risk"
      ]
    }
  },
  "thesis": {
    "statement": "Filing-confirmed growth plus a small size makes the valuation risk acceptable; invalidation conditions bound the downside.",
    "confidence": 0.7,
    "invalidation_conditions": [
      "Next filing misses revenue",
      "Close below the invalidation level"
    ]
  },
  "decision": {
    "action": "add",
    "rationale": "Primary evidence supports growth; the small add and invalidation conditions bound the valuation risk.",
    "evidence_ids": [
      "filing-growth",
      "valuation-risk"
    ],
    "order": {
      "side": "buy",
      "quantity": "200",
      "unit_price": "310.00",
      "quote_currency": "HKD",
      "gross_amount_quote": "62000.00",
      "base_currency": "HKD",
      "fx_quote_to_base": "1",
      "gross_amount_base": "62000.00"
    }
  }
}

{
  "schema_version": 1,
  "workflow": {
    "id": "investment-decision",
    "version": "1.1.0"
  },
  "decision_id": "example-2026-08-08",
  "observed_at": "2026-08-09T08:00:00+00:00",
  "evidence": {
    "source": "broker closing-price export",
    "source_class": "broker",
    "quote_currency": "USD",
    "entry_price": "100.00",
    "outcome_price": "102.00",
    "base_currency": "HKD",
    "entry_fx_quote_to_base": "7.80",
    "outcome_fx_quote_to_base": "7.81"
  }
}

# Decision artifact contract

`decision.json` is the single required artifact for workflow version `1.1.0`.
Unknown or missing fields are rejected so a producer cannot silently invent a
parallel schema.

The machine-readable shape is `decision.schema.json` in this directory. JSON
Schema covers structure and primitive types; clawock's Python validator adds the
cross-reference, provenance, opposing-evidence, action/order and arithmetic
invariants that JSON Schema cannot express.

## Top-level fields

- `schema_version`: integer `1`.
- `workflow`: exactly `{"id":"investment-decision","version":"1.1.0"}`.
- `decision_id`: stable non-empty identifier chosen by the calling runtime.
- `as_of`: ISO-8601 timestamp with timezone.
- `subject`: `ticker`, `market`, and quote `currency` strings.
- `evidence`: traceable evidence rows.
- `debate`: one bull and one bear case, each linked to evidence IDs.
- `thesis`: statement, confidence from 0 to 1, and non-empty invalidation conditions.
- `decision`: bounded action, rationale, evidence links, and optional order intent.

## Evidence

Each row contains exactly:

- `id`: unique non-empty string.
- `stance`: `supporting`, `opposing`, or `context`.
- `summary`: the observed fact, not an unsupported conclusion.
- `source`: a stable locator or source name.
- `source_class`: `primary`, `secondary`, `market`, or `agent`.
- `observed_at`: ISO-8601 timestamp with timezone, no later than `as_of`.

The bull case must cite supporting evidence and the bear case must cite opposing
evidence. Every cited ID must exist. The configured workflow parameters control
minimum evidence counts and the maximum confidence allowed without a cited
primary source.

## Decision and order intent

`action` is one of `buy`, `add`, `hold`, `watch`, `trim`, `sell`, `exit`, or
`abstain`. `hold`, `watch`, and `abstain` carry `order: null`. Other actions
carry an order with exactly:

- `side`: `buy` or `sell`, consistent with the action.
- `quantity`, `unit_price`, `gross_amount_quote`.
- `quote_currency`, `base_currency`.
- `fx_quote_to_base`, `gross_amount_base`.

All numeric values must be positive and finite. clawock reconciles the two money
identities to currency cents:

`gross_amount_quote = quantity * unit_price`

`gross_amount_base = gross_amount_quote * fx_quote_to_base`

See `assets/decision.example.json` for a complete watch decision, and
`assets/order.example.json` for an order-carrying decision with both money
identities reconciled.

## Outcome evidence and evaluation

Copy `assets/outcome.example.json`, preserve the decision/workflow identifiers,
and replace the price, FX, timestamp, and source fields with observed evidence.
Then run:

```bash
clawock workflow evaluate investment-decision \
  --decision decision.json --outcome outcome.json --output evaluation.json
```

The evaluator calculates quote-currency and base-currency market moves in basis
points. `decision_value_bps` applies +1 to long/hold decisions, -1 to
trim/sell/exit decisions, and 0 to watch/abstain. This is a reproducible
directional evaluation, not realized P&L; portfolio cash, fills, fees, taxes and
position size remain outside this artifact.

## Bounded improvement

An external runtime or human can propose only parameters already bounded by
`workflow.json`:

```bash
clawock workflow propose --workspace . --trigger evaluation.json \
  --set min_opposing_evidence=2 \
  --rationale "Weak opposing evidence preceded the measured miss." \
  --expected-effect "Require a second independent opposing source." \
  --output proposal.json

clawock workflow review --proposal proposal.json --decision accepted \
  --reviewer analyst@example --note "Evidence supports a bounded trial." \
  --output review.json

clawock workflow apply --workspace . --proposal proposal.json --review review.json
clawock workflow rollback --workspace . --change-id <change-id>
```

The trigger can also be a rejected `clawock run publish` receipt. A proposal
pins the workflow version/certificate, trigger hash, old/new values and expected
effect. Apply refuses rejected or mismatched reviews, stale parameters, unknown
settings and values outside their declared bounds. Rollback refuses to overwrite
later parameter drift.

This loop never launches a model, edits `SKILL.md`, changes OpenClaw memory/chat
behavior or accepts its own proposal. Reasoning stays in the external runtime;
clawock owns the evidence link, deterministic math and reversible adoption
record.

The bounded parameters change workflow evidence strictness only. They do not
introduce or tune quantitative factors, catalysts, signals, entry/exit rules or
portfolio construction; those remain part of the caller's existing strategy.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:clawock:workflow:investment-decision:1.1.0:decision",
  "title": "clawock investment decision",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "workflow",
    "decision_id",
    "as_of",
    "subject",
    "evidence",
    "debate",
    "thesis",
    "decision"
  ],
  "properties": {
    "schema_version": {
      "const": 1
    },
    "workflow": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "version"],
      "properties": {
        "id": {"const": "investment-decision"},
        "version": {"const": "1.1.0"}
      }
    },
    "decision_id": {
      "type": "string",
      "minLength": 1
    },
    "as_of": {
      "type": "string",
      "format": "date-time"
    },
    "subject": {
      "type": "object",
      "additionalProperties": false,
      "required": ["ticker", "market", "currency"],
      "properties": {
        "ticker": {"type": "string", "minLength": 1},
        "market": {"type": "string", "minLength": 1},
        "currency": {"type": "string", "minLength": 1}
      }
    },
    "evidence": {
      "type": "array",
      "items": {"$ref": "#/$defs/evidence"}
    },
    "debate": {
      "type": "object",
      "additionalProperties": false,
      "required": ["bull_case", "bear_case"],
      "properties": {
        "bull_case": {"$ref": "#/$defs/case"},
        "bear_case": {"$ref": "#/$defs/case"}
      }
    },
    "thesis": {
      "type": "object",
      "additionalProperties": false,
      "required": ["statement", "confidence", "invalidation_conditions"],
      "properties": {
        "statement": {"type": "string", "minLength": 1},
        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
        "invalidation_conditions": {
          "type": "array",
          "minItems": 1,
          "items": {"type": "string", "minLength": 1}
        }
      }
    },
    "decision": {
      "type": "object",
      "additionalProperties": false,
      "required": ["action", "rationale", "evidence_ids", "order"],
      "properties": {
        "action": {
          "enum": ["buy", "add", "hold", "watch", "trim", "sell", "exit", "abstain"]
        },
        "rationale": {"type": "string", "minLength": 1},
        "evidence_ids": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {"type": "string", "minLength": 1}
        },
        "order": {
          "oneOf": [
            {"type": "null"},
            {"$ref": "#/$defs/order"}
          ]
        }
      }
    }
  },
  "$defs": {
    "evidence": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "stance", "summary", "source", "source_class", "observed_at"],
      "properties": {
        "id": {"type": "string", "minLength": 1},
        "stance": {"enum": ["supporting", "opposing", "context"]},
        "summary": {"type": "string", "minLength": 1},
        "source": {"type": "string", "minLength": 1},
        "source_class": {"enum": ["primary", "secondary", "market", "agent"]},
        "observed_at": {"type": "string", "format": "date-time"}
      }
    },
    "case": {
      "type": "object",
      "additionalProperties": false,
      "required": ["summary", "evidence_ids"],
      "properties": {
        "summary": {"type": "string", "minLength": 1},
        "evidence_ids": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {"type": "string", "minLength": 1}
        }
      }
    },
    "positive-number": {
      "oneOf": [
        {"type": "number", "exclusiveMinimum": 0},
        {"type": "string", "pattern": "^(?:0*[1-9][0-9]*(?:\\.[0-9]+)?|0*\\.[0-9]*[1-9][0-9]*)$"}
      ]
    },
    "order": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "side",
        "quantity",
        "unit_price",
        "quote_currency",
        "gross_amount_quote",
        "base_currency",
        "fx_quote_to_base",
        "gross_amount_base"
      ],
      "properties": {
        "side": {"enum": ["buy", "sell"]},
        "quantity": {"$ref": "#/$defs/positive-number"},
        "unit_price": {"$ref": "#/$defs/positive-number"},
        "quote_currency": {"type": "string", "minLength": 1},
        "gross_amount_quote": {"$ref": "#/$defs/positive-number"},
        "base_currency": {"type": "string", "minLength": 1},
        "fx_quote_to_base": {"$ref": "#/$defs/positive-number"},
        "gross_amount_base": {"$ref": "#/$defs/positive-number"}
      }
    }
  }
}