okra

Okra

Okra packages the reverse-tornado-okr skill: a workflow for turning a goal into a measured, self-correcting OKR loop with an anti-goal guardrail.

The repo is set up as a skill development workspace:

• Canonical skill: skills/reverse-tornado-okr/SKILL.md
• Blindbox evals: evals/blindbox/
• Review prompt: evals/review/skill-review.md
• Runner: scripts/okr-runner.py

What The Skill Does

Use the skill when a user is setting OKRs, defining measurable goals, planning a roadmap toward a metric, or delegating goal execution while keeping human control of direction.

It produces:

• objective and target metric
• measured anti-goal and guardrail type
• DKR/CKR/PKR decomposition
• three-point anti-goal evaluation
• escalation flags and human-owned frame
• operating-loop cadence for recurring or automated runs
• OKRA learning memory for recurring project contexts
• executable claim contracts: progress claims and DKR checkpoints carry replayable evidence

(metric id, threshold, source of truth, replay command), like anti-goal claims

• process-signal events (handback, regression, rework, late discovery, empty DKR, ungoverned

write) as append-only ledger records; counters are derived by okra-store.sh counts, never typed

• a computed risk register: per-branch windowed risk_score recomputed from events

(okra-store.sh risk-read refuses a typed score), with stalled as the fourth outcome flag

• write-once estimation records at dispatch with backfit detection and

okra-store.sh calibration recompute

• check-in sweeps (5-Why uncertainty drill, hallucination/missing-context, evidence-ref'd) and

event-derived reinforcement records, with narrative-vs-ledger reconciliation

For real-life runs, the skill requires metric freshness contracts, heartbeat cadence, lag windows, flag lifecycle, action envelope, and idempotent storage.

For dogfooded development in this repo, .claude/agents/ defines the three-role loop: an orchestrator that steers and never executes, an okra-writer that progresses work and never self-certifies, and an okra-validator that replays every claim into fail-closed audit traces.

Install

The skill is distributed as a plain skill, not a Claude Code or Codex plugin. Install it with bunx skills:

bunx skills add lagz0ne/okra

This writes an entry to your project's skills-lock.json pinned to a commit hash. Update it later with:

bunx skills update reverse-tornado-okr

Codex

Validate the skill and eval harness:

scripts/validate-skills.sh
scripts/run-blindbox.sh --dry-run --agent both

The repo-local skill links are:

.claude/skills/reverse-tornado-okr -> ../../skills/reverse-tornado-okr
.codex/skills/reverse-tornado-okr -> ../../skills/reverse-tornado-okr

To repair or verify those links explicitly:

python3 scripts/okr-runner.py skill-links install
python3 scripts/okr-runner.py skill-links verify

This repository dogfoods the skill. For non-trivial work on the skill, runner, evals, review harness, release workflow, or OKRA memory, use reverse-tornado-okr as the default workflow. The default trust anti-goal is single_llm_truth_acceptance_count == 0; judgement-heavy claims need deterministic evidence where possible plus independent Codex/Claude or human review before they are accepted.

Real Eval

Run a real isolated eval when Claude/Codex credentials are available:

CODEX_MODEL=<codex-model> ANTHROPIC_MODEL=<claude-model> \
scripts/run-blindbox.sh --agent both --case real-life-operations

For the cross-run learning-memory case:

CODEX_MODEL=<codex-model> ANTHROPIC_MODEL=<claude-model> \
scripts/run-blindbox.sh --agent both --case okra-learning-memory

For project-default dogfooding behavior, run the natural prompt case that does not inject skill fallback context:

CODEX_MODEL=<codex-model> ANTHROPIC_MODEL=<claude-model> \
scripts/run-blindbox.sh --agent both --case okra-default-dogfood

To compare Claude model behavior across the current Opus and Sonnet verification set, run the Claude-only model matrix. The default matrix is claude-opus-4-8 and claude-sonnet-5; override it with ANTHROPIC_MODEL_MATRIX when needed.

scripts/run-claude-model-matrix.sh --case okra-handoff-contracts

After each scored model run, the matrix wrapper reruns the current deterministic checkers over the preserved workspace and writes recheck.json next to result.json. Recheck also validates the preserved result.sha256, prompt/input hashes, workspace output hashes, changed-path allowlist, and credential/runtime cleanup checks. To validate the latest preserved Opus/Sonnet artifacts without spending model calls, run:

scripts/run-claude-model-matrix.sh --recheck-latest --case okra-handoff-contracts

The runner copies a fixture into .runs/, injects the skill into a disposable workspace, launches the selected agent through bwrap, and preserves prompts, logs, outputs, hashes, and check results. Writable agent scratch lives under each run's runtime/ directory, is checked for post-run cleanup, and is excluded from preserved-artifact credential scans after cleanup. If cleanup fails, the leftover runtime/ tree is scanned and hashed by the cleanup check.

Review

Before releasing skill or harness changes, run:

scripts/review-skill.sh --agent both

Review outputs land under .runs/review/. In diff mode, small safe untracked files are embedded with secret-line redaction. Reviewers read listed skipped or non-embedded paths directly before signing off.

Release

Releases are marked with a git tag (okra--vX.Y.Z) on main; there is no separate manifest version to keep in sync.

git tag okra--vX.Y.Z
git push origin main --tags

License

MIT