v0.7.0 — Option-level effects + runtime introspection

Highlights

This release redesigns x-agent policy derivation from command-level static annotations to option-level effect declarations with runtime introspection (--introspect).

New Features

• Option-level and command-level effects declarations — declare writes, reads, network calls, risk levels, execution mode, and idempotency at the point where they occur
• --introspect global option — generated CLIs can output derived policy as JSON without executing
• policy.ts generated file — deterministic policy derivation engine (derivePolicy() pure function)
• Effect-level idempotency — effects.writes[].idempotent, effects.network.idempotent with idempotencyKey and idempotentNote
• Aggregated idempotent in DerivedPolicy — true only when all writes and network effects are explicitly idempotent

Deprecations

The following x-agent fields are now deprecated in favor of effects declarations:

• riskLevel → effects.riskLevel
• sideEffects → effects.writes / effects.network
• sideEffectNote → effects.writes[].description
• requiresConfirmation → derived from riskLevel >= high
• requiresConfirmationWhen / dangerousOptions → option-level effects.riskLevel
• safeDryRunOption → --introspect
• requiresNetwork / requiresSecrets → effects.network / env[].sensitive
• reads / writes → effects.reads / effects.writes
• idempotent / idempotentNote → effects.writes[].idempotent / effects.network.idempotent

Using deprecated fields alongside effects produces validation warnings.

Migration

# Before
lint:
  x-agent:
    riskLevel: low
    sideEffects: [file_write]
    sideEffectNote: "only when --fix"
    idempotent: true

# After
lint:
  options:
    - name: fix
      effects:
        riskLevel: medium
        writes:
          - target: "source files matching lint rules"
            idempotent: true

Other Changes

• cli-contract.yaml migrated to effects-based declarations
• README updated with effects documentation
• CLI reference regenerated