← Back to file list
Helper Surface
The exact deterministic helper commands and what each one writes.
Workflow Rules · /home/jonas/social-carousel-codex/docs/helper-surface.md
Last modified: 2026-03-29T12:51:40.856Z
# Helper Surface ## Purpose Phase 6 turns the main missing business stages into explicit deterministic commands in `scripts/runtime_state.py`. Primary entry point: ```bash python3 scripts/runtime_state.py <command> ... ``` Every stage helper writes: - the durable artifact under `state/ideas/<idea_id>/` - the updated `ledger.json` - one append-only event in `state/logs/<idea_id>.ndjson` - one immutable checkpoint in `state/checkpoints/<idea_id>/` Lightweight operator commands now exist as read-oriented helpers so approval-gated runs require less manual file opening: - `show-current-run-state` - `show-benchmark-diagnosis` - `show-angle-options` - `show-research-package` - `show-latest-preview` - `show-version-history` ## Intake ```bash python3 scripts/runtime_state.py record-intake <idea_id> <input.json> ``` Writes: - `state/ideas/<idea_id>/intake.json` - `state/ideas/<idea_id>/ledger.json` Ledger target: - `stage: intake_recorded` - `current_action: await_angle_generation` - `current_action_status: ready` For benchmark-first intake, `record-intake` now accepts structured benchmark context inside `intake.json` and moves the ledger to: - `stage: benchmark_analysis_pending` - `current_action: analyze_benchmark` - `current_action_status: waiting_human` Benchmark-first intake can now persist: - `start_mode: benchmark_first` - `operator_context` - `benchmark.screenshot_path` - optional `benchmark.url` ## Benchmark Diagnosis ```bash python3 scripts/runtime_state.py record-benchmark-diagnosis <idea_id> <input.json> python3 scripts/runtime_state.py show-benchmark-diagnosis <idea_id> python3 scripts/runtime_state.py generate-benchmark-angle-set <idea_id> ``` `record-benchmark-diagnosis` writes: - `state/ideas/<idea_id>/benchmark-diagnosis.json` Ledger target: - `stage: benchmark_diagnosed` - `current_action: generate_benchmark_angles` - `current_action_status: ready` `generate-benchmark-angle-set` then reads the persisted intake plus benchmark diagnosis and writes the normal `angle-set.json`. For benchmark-first runs, `record-angle-set` now fails closed if `benchmark-diagnosis.json` does not exist yet. ## Angles ```bash python3 scripts/runtime_state.py record-angle-set <idea_id> <input.json> python3 scripts/runtime_state.py approve-angle <idea_id> <input.json> ``` `record-angle-set` writes: - `state/ideas/<idea_id>/angle-set.json` Ledger target: - `stage: angle_pending_approval` - `current_action: await_angle_approval` - `current_action_status: waiting_human` `approve-angle` writes: - `state/ideas/<idea_id>/angle-approval.json` Ledger target: - `selected_angle` - `stage: research_in_progress` - `current_action: prepare_research_package` - `current_action_status: ready` Approval input only needs the explicit decision payload, for example: ```json { "option_number": 2, "selected_at": "2026-03-29T10:00:00+07:00" } ``` ## Research Persistence Primary wrapper: ```bash python3 scripts/literature_review_wrapper.py build-package <spec.json> python3 scripts/literature_review_wrapper.py build-package <spec.json> --summary-only ``` Underlying helper commands: ```bash python3 scripts/runtime_state.py record-research-summary <idea_id> <input.json> python3 scripts/runtime_state.py approve-research <idea_id> <input.json> python3 scripts/runtime_state.py approve-research-proposal <idea_id> ``` `record-research-summary` writes: - `state/ideas/<idea_id>/research-summary.json` Ledger target: - `stage: research_pending_approval` - `current_action: await_research_approval` - `current_action_status: waiting_human` `approve-research` writes: - `state/ideas/<idea_id>/research-lock.json` Ledger target: - `research_lock` - `stage: draft_in_progress` - `current_action: prepare_draft` - `current_action_status: ready` `scripts/literature_review_wrapper.py` is now the repo-local adapter around the OpenClaw search script. It writes search artifacts under `artifacts/research/<idea_id>/<research_bundle_id>/`. Use it in one of two modes: - default mode: persists `research-summary.json`, writes `research-lock-proposal.json`, writes `research-lock-approval-input.json`, and then persists `research-lock.json` - `--summary-only`: persists only `research-summary.json` and stops at the human approval gate while writing `research-lock-proposal.json` For supervised human-gated runs, prefer `--summary-only` and then use: ```bash python3 scripts/runtime_state.py show-research-package <idea_id> python3 scripts/runtime_state.py approve-research-proposal <idea_id> ``` Optional explicit approval timestamp: ```bash python3 scripts/runtime_state.py approve-research-proposal <idea_id> --approved-at 2026-03-29T10:00:00+07:00 ``` This helper reads the current `research-lock-proposal.json`, writes `research-lock-approval-input.json`, persists `research-lock.json`, and advances the ledger into drafting without hand-authoring a separate approval payload. Migration note: - older Phase 7 research bundles may still contain `research-lock-input.json` - new bundles split pre-approval and approval-only artifacts into `research-lock-proposal.json` and optional `research-lock-approval-input.json` ## Drafts ```bash python3 scripts/runtime_state.py commit-draft <idea_id> <draft.json> ``` Writes: - `state/ideas/<idea_id>/drafts/<draft_version_id>.json` Rules: - `carousel_id` must match `<idea_id>` - non-root drafts must reference an existing parent file - an existing version id cannot be overwritten with different content - `research-lock.json` must already exist - root drafts are only valid when the ledger is ready for `prepare_draft` - revised drafts are only valid when the ledger is ready for `commit_revised_draft` or `revise_draft` Contract enforcement: - `commit-draft` fails closed on template-contract violations before the draft is persisted - the same authoring validator is reused inside `run-qc` through `draft_shape_valid` - character-limit failures are therefore surfaced as deterministic revise-and-retry feedback, not soft review notes Ledger target: - `latest_draft` - `revision.draft_version` - `stage: validation_in_progress` - `current_action: run_qc` - `current_action_status: ready` ## QC ```bash python3 scripts/runtime_state.py run-qc <idea_id> python3 scripts/runtime_state.py run-qc <idea_id> --version V2 python3 scripts/runtime_state.py run-qc <idea_id> --path /tmp/draft.json ``` Writes: - `state/ideas/<idea_id>/qc-result.json` - `state/ideas/<idea_id>/qc-results/<draft_version>.json` Pass behavior: - `latest_verified_draft` - `revision.latest_verified_version` - `stage: preview_ready` - `current_action: build_preview_payload` - `current_action_status: ready` Fail behavior: - `retry_counters.validation += 1` - `stage: validation_in_progress` - `current_action: revise_draft` - `current_action_status: blocked` ## Preview ```bash python3 scripts/runtime_state.py build-preview-payload state/ideas/<idea_id>/drafts/V1.json /tmp/<idea_id>-preview.json python3 scripts/runtime_state.py materialize-preview /tmp/<idea_id>-preview.json python3 scripts/runtime_state.py verify-preview <folder_name> --idea-id <idea_id> --version V1 --base-url http://127.0.0.1:3101 python3 scripts/runtime_state.py record-preview <idea_id> /tmp/<idea_id>-preview.json --version V1 ``` Optional public-host verification: ```bash python3 scripts/runtime_state.py verify-preview <folder_name> --idea-id <idea_id> --version V1 --base-url http://127.0.0.1:3101 --public-base-url https://agent.jonaswilbert.com ``` `build-preview-payload` now derives `folder_name` from both the idea id and the draft version, for example `idea-20260329-protein-breakfast-satiety-realrun-01-v2`. `record-preview` writes: - `state/ideas/<idea_id>/preview.json` - `state/ideas/<idea_id>/preview-records/<draft_version>.json` Ledger target: - `latest_preview` - `revision.preview_version` - `stage: preview_pending_decision` - `current_action: await_preview_decision` - `current_action_status: waiting_human` When public-host verification succeeds: - `verification.json` prefers the public verified `viewer_url` and `api_url` - `preview.json` and `ledger.latest_preview.url` use that public review URL as the canonical surfaced preview URL - artifact-local URLs remain preserved in the verification record Migration note: - older preview bundles under `artifacts/previews/<idea-slug>/` remain valid and can still be reverified - new preview payloads materialize forward-only into version-specific folders under `artifacts/previews/<idea-slug>-<draft-version>/` ## Operator Commands Use these to inspect the durable state at human gates instead of opening multiple JSON files by hand: ```bash python3 scripts/runtime_state.py show-current-run-state <idea_id> python3 scripts/runtime_state.py show-benchmark-diagnosis <idea_id> python3 scripts/runtime_state.py show-angle-options <idea_id> python3 scripts/runtime_state.py show-research-package <idea_id> python3 scripts/runtime_state.py show-latest-preview <idea_id> python3 scripts/runtime_state.py show-version-history <idea_id> ``` They are read-only and do not mutate workflow state. ## Revision Classification ```bash python3 scripts/runtime_state.py classify-revision <idea_id> <input.json> ``` Writes: - `state/ideas/<idea_id>/revision-classification.json` Allowed classifications: - `design_only` - `copy_within_lock` - `research_required` - `concept_restart` The input also carries explicit meaning-change flags. The helper derives `qc_required` from: - `changes_meaning_bearing_text` - `changes_claim_interpretation` - `changes_certainty` - `changes_health_implications` Default `copy_within_lock` examples: - shorten the cover without changing the claim - make the cover more curiosity-driven without widening the approved claim envelope - rewrite slides into clearer consumer-facing language - translate evidence caveats into more natural consumer language without changing the evidence boundary - expand to 4 or more content slides without adding a new claim - improve standalone readability, non-repetition, or story flow inside the current lock Ledger targets by class: - `design_only` -> `stage: revision_design_only`, `current_action: regenerate_preview` - `copy_within_lock` -> `stage: revision_copy_within_lock`, `current_action: commit_revised_draft` - `research_required` -> `stage: research_in_progress`, `current_action: prepare_research_package` - `concept_restart` -> `stage: concept_restart_required`, `current_action: generate_new_angles` ## Final Approval ```bash python3 scripts/runtime_state.py final-approve <idea_id> <input.json> ``` Writes: - `state/ideas/<idea_id>/final-approval.json` Requirements: - `latest_preview` exists - preview status is `verified` - approved version matches the verified preview version - `latest_verified_draft` matches the same version Minimal approval input: ```json { "approved_at": "2026-03-29T19:24:32+07:00", "approved_version": "V2", "notes": "Accepted as the final approved version for this run." } ``` Ledger target: - `status: complete` - `stage: complete` - `current_action: approved` - `current_action_status: complete` ## Failure Handling Existing bounded failure commands still apply: ```bash python3 scripts/runtime_state.py park-idea state/ideas/<idea_id>/ledger.json --reason "<reason>" python3 scripts/runtime_state.py move-to-dlq state/ideas/<idea_id>/ledger.json --reason "<reason>" ``` `park-idea` now writes: - the parked `ledger.json` - one append-only `PARKED` event - one immutable parked checkpoint Use it when a run is intentionally paused for workflow or operator reasons and the current artifacts should remain intact. Use them after reading the latest checkpoint and log, not as a substitute for normal stage helpers.
Save
Ready